> ## Documentation Index
> Fetch the complete documentation index at: https://legitimuz.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# 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.

<Info>
  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.
</Info>

## 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](/api/verification-statuses):

```json theme={null}
{
  "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"
}
```

<Info>
  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.
</Info>

## 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.