Skip to main content

​
Por que configurar um webhook

Sem webhook, você precisa chamar GET /report/:id repetidamente até o relatório ficar pronto. Com webhook, a GYRA+ avisa você assim que o resultado estiver disponível — mais eficiente, mais confiável.

​
Pré-requisitos

  • Token JWT válido (veja autenticação)
  • Um endpoint HTTPS público e acessível que responda HTTP 200

​
Passo 1 — Crie seu endpoint

Seu servidor precisa de um endpoint que aceite POST e responda 200 rapidamente. 
app.post('/webhooks/gyra', (req, res) => {
  // Responder 200 imediatamente
  res.sendStatus(200);

  // Processar de forma assíncrona
  const { reportId, policyStatus, score, externalId } = req.body;
  processarDecisao({ reportId, policyStatus, score, externalId });
});
Nunca processe o payload de forma síncrona antes de responder 200. Se o seu servidor demorar para responder, a GYRA+ pode tentar reenviar.

​
Passo 2 — Registre a URL

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"
  }'
Resposta: 
{
  "id": "64a3b2c1d4e5f6a7b8c9d0e2",
  "url": "https://seu-sistema.com/webhooks/gyra",
  "createdAt": "2025-03-01T10:00:00.000Z"
}

​
Passo 3 — Teste o recebimento

Crie um relatório e monitore se o webhook chega: 
curl -X POST https://gyra-core.gyramais.com.br/report \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "document": "43591367000130",
    "type": "CNPJ",
    "policyId": "679955e0485aa2f033203f98",
    "externalId": "teste-webhook-01"
  }'
Após 30–90 segundos (dependendo das integrações ativas), seu endpoint deve receber: 
{
  "reportId": "64a3b2c1d4e5f6a7b8c9d0e1",
  "document": "43591367000130",
  "type": "CNPJ",
  "status": "APPROVED",
  "policyStatus": "APPROVED",
  "score": 720,
  "externalId": "teste-webhook-01",
  "createdAt": "2025-03-01T10:30:00.000Z",
  "completedAt": "2025-03-01T10:31:05.000Z"
}

​
Gerenciar webhooks

Listar webhooks cadastrados: 
curl https://gyra-core.gyramais.com.br/webhook/findby \
  -H "Authorization: Bearer {token}"
Remover um webhook: 
curl -X DELETE https://gyra-core.gyramais.com.br/webhook/{id} \
  -H "Authorization: Bearer {token}"

​
Boas práticas

PráticaPor quê
Responder 200 em menos de 3 segundosEvita retentativas desnecessárias
Usar externalId para rastrearFacilita o vínculo com seu sistema sem consultar a API
Implementar idempotênciaO mesmo reportId pode chegar mais de uma vez em casos de retry
Ter fallback com GET /report/:idPara casos em que o webhook falha por indisponibilidade temporária
Usar HTTPS com certificado válidoRequisito de segurança — HTTP não é aceito