Webhooks

Receba a decisão das verificações no seu backend, com entrega assinada e rastreável.

A decisão de uma verificação nunca chega ao navegador: ela é entregue ao seu backend por webhook. Você registra destinos (uma URL e a lista de eventos que ela recebe) e trata as entregas.

O disparo de webhooks está em implementação. O modelo de destinos e entregas abaixo já é o definitivo, e os nomes de evento também — o que falta é o disparo em si e o esquema de assinatura, publicados quando fecharem.

Destinos

Um destino é uma URL HTTPS mais a lista de eventos que ela assina. Na criação, você recebe o segredo de assinatura do destino uma única vez, como a chave de API. Guarde-o para conferir as entregas.

O destino pode estar ativo ou pausado, e você alterna entre os dois. O terceiro estado, falhando, é veredito do sistema sobre as entregas: ele existe para você perceber um endpoint quebrado, não para ser declarado.

Eventos

Os nomes de evento já estão decididos — são os mesmos que cada entrega grava:

Evento	Quando dispara
verification.created	Uma verificação foi criada
verification.updated	O status de uma verificação mudou
verification.approved	Uma verificação foi aprovada
verification.reproved	Uma verificação foi reprovada
verification.review	Uma verificação entrou em revisão manual
verification.expired	Uma verificação expirou sem desfecho
flow.published	Uma nova versão do fluxo foi publicada

O evento de verificação carrega o status atual:

{
  "event": "verification.updated",
  "verification_id": "0197f3a1-8c4d-7b2e-9f01-2a3b4c5d6e7f",
  "ref_id": "pedido-4821",
  "status": "approved",
  "identity_score": 71,
  "fraud_score": 54,
  "occurred_at": "2026-08-10T13:02:44Z"
}

O payload acima é o preview que o dashboard já mostra ao cadastrar um destino. O endpoint que serve esse catálogo formalmente (com descrição e exemplo por evento) ainda não existe — os nomes não mudam quando ele for publicado.

Entregas

Cada tentativa de entrega fica registrada com dois campos separados de propósito: o código HTTP que o seu endpoint devolveu, e o status lógico da entrega (pendente, entregue ou falha). O código registra o que o seu endpoint respondeu naquela tentativa; o status diz se a entrega foi concluída, considerando as novas tentativas.

Responda 2xx rápido e processe o payload de forma assíncrona: o veredito de entrega é sobre a recepção, não sobre o seu processamento.

Assinatura

Toda entrega é assinada com o segredo do destino, para o seu backend rejeitar chamadas que não vieram da Legitimuz.

Boas práticas

• Deduplique por evento, não por chegada: novas tentativas reenviam o mesmo evento.
• Não confie em ordem de chegada entre eventos diferentes.
• Valide a assinatura antes de ler o payload. Endpoint de webhook sem validação é uma porta para decisão forjada.