Skip to main content

​
Por que usar webhooks

O processamento de um relatório GYRA+ é assíncrono — consultas externas como Serasa, SCR e certidões levam tempo. Em vez de consultar GET /report/:id repetidamente, configure um webhook para receber o resultado assim que estiver pronto. Isso é a base de qualquer integração robusta com a GYRA+.

​
Como funciona

  1. Você cria o relatório com POST /report
  2. Recebe imediatamente o reportId e o status PENDING
  3. A GYRA+ processa em background
  4. Quando concluído, envia um POST para a URL do seu webhook com o resultado completo

​
Payload do webhook

Quando o relatório é concluído, a GYRA+ envia um POST para sua URL com o seguinte payload: 
{
  "reportId": "64a3b2c1d4e5f6a7b8c9d0e1",
  "document": "43591367000130",
  "type": "CNPJ",
  "status": "APPROVED",
  "policyStatus": "APPROVED",
  "score": 720,
  "externalId": "pedido-123",
  "createdAt": "2025-03-01T10:30:00.000Z",
  "completedAt": "2025-03-01T10:30:45.000Z"
}
CampoTipoDescrição
reportIdstringID do relatório na GYRA+
documentstringCPF ou CNPJ consultado
typestringCPF ou CNPJ
statusstringStatus geral: APPROVED, DENIED, ALERT
policyStatusstringResultado da política de crédito
scorenumberScore final (0–1000)
externalIdstringIdentificador do seu sistema (se enviado no POST /report)

​
Configurando um webhook

1

Crie o endpoint no seu sistema

O endpoint deve estar acessível publicamente e responder HTTP 200 para confirmar o recebimento.
2

Registre a URL na GYRA+

curl -X POST https://gyra-core.gyramais.com.br/webhook \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://seu-sistema.com/webhooks/gyra",
    "events": ["report.completed"]
  }'
3

Teste o recebimento

Crie um relatório de teste e valide que o payload chegou corretamente no seu endpoint.

​
Boas práticas

Seu endpoint de webhook deve responder HTTP 200 o mais rápido possível — antes de qualquer processamento pesado. Processe o payload de forma assíncrona na sua fila interna.
Ao criar o relatório, passe o externalId com o identificador do seu sistema (ID do pedido, ID do cliente, etc.). O webhook retornará esse campo, facilitando o vínculo com sua base de dados.
Verifique os campos status e policyStatus antes de tomar qualquer ação no seu sistema. Um status: APPROVED com policyStatus: ALERT pode ter tratamento diferente.
Em caso de indisponibilidade temporária do seu endpoint, implemente um fallback com GET /report/:id para não perder resultados.

​
Referência de eventos

EventoDescrição
report.completedRelatório concluído (aprovado, negado ou alerta)
Mais eventos serão adicionados em versões futuras da API. Acompanhe o Changelog para novidades.