Skip to main content
Esta página descreve Webhooks (Notificações Automáticas). A configuração na plataforma fica em Webhooks e API Keys. A configuração via API fica em Criar Webhook.

​
Por que usar webhooks

O processamento de um relatório GYRA+ é assíncrono, consultas a bureaus de crédito, SCR/Open Finance 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

​
Tipos de evento

Cada webhook é registrado para um único tipo de evento. Para escutar mais de um, registre webhooks separados.

​
Payload do webhook

Todo disparo é um POST com envelope:
O conteúdo de data depende do tipo. Exemplo para REPORT_FINISHED:
Estrutura de data para os demais tipos e exemplos completos em Webhooks e API Keys.

​
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+

Um webhook por type. Para escutar múltiplos eventos, registre um por tipo.
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.

​
Retry

A GYRA+ tenta entregar cada evento até 3 vezes com backoff exponencial (1s, ~2s, ~5s). Se o seu endpoint retornar 429 com Retry-After, a GYRA+ respeita esse tempo. Após as tentativas, o evento é descartado — mantenha fallback com polling em GET /v2/report/:id para eventuais perdas e planeje idempotência no seu lado.