# Recebendo resultados de verificação com webhooks

Source: https://help.didit.me/pt-BR/integration/webhooks-basics
Updated: 2026-10-12

Um webhook avisa o seu backend quando um status muda. Crie em Desenvolvedores, Webhooks, inscreva cada evento e verifique a assinatura antes de processar.

Um webhook é uma requisição HTTP que a Didit envia para a sua URL quando algo muda.
Adicione um destino em **Desenvolvedores → Webhooks**, inscreva-se nos eventos que você
quer - não existe **curinga**, liste cada um - guarde o signing secret, e verifique
a assinatura antes de processar qualquer coisa.

[Video: Visão geral dos webhooks - Didit Academy](https://www.youtube.com/watch?v=fX03-WEu_EI&t=192)

A Didit não envia um e-mail quando uma sessão passa para **In Review** ou **Declined**. Para saber no exato momento em que um status muda, sem precisar atualizar o console, configure um webhook - uma URL no seu servidor para a qual a Didit envia a atualização automaticamente.

Webhooks são o padrão de integração **recomendado**. Fazer polling no endpoint de decisão funciona como alternativa, mas é mais lento, custa mais requisições, e perde eventos que só são entregues por webhook - edições de dados feitas por um revisor, mudanças de status de transação, e mudanças em nível de entidade.

## Configurando um

1. **Desenvolvedores → Webhooks**

   Abra a aplicação e o ambiente Live ou Sandbox corretos, depois Desenvolvedores e Webhooks.

2. **Adicione um endpoint**

   Clique em Adicionar endpoint, informe a URL HTTPS e o nome e selecione eventos. Mantenha a versão recomendada v3, salvo ao manter uma integração antiga. Revise e confirme.

3. **Salve o segredo de assinatura**

   Cada endpoint tem seu próprio segredo de assinatura oculto. Clique em Revelar e confirme sua identidade; ele volta a ficar oculto em até 60 segundos. Guarde na configuração do servidor. Contate o suporte se Revelar estiver desativado. [Desenvolvedores → Webhooks](https://docs.didit.me/integration/webhooks#signature-verification).

4. **Envie um evento de teste**

   Envie um evento de teste assinado para validar o endpoint, a assinatura e o processamento sem executar uma verificação real.

![Destinos de webhook no console da Didit com eventos inscritos e histórico de entregas](https://help.didit.me/screenshots/webhooks-light.webp)

*Cada destino tem seus próprios eventos inscritos, signing secret e log de entregas.*

## Os eventos aos quais você pode se inscrever

Não existe **curinga** - liste cada família de eventos que você quer. Distribuí-los entre vários destinos é aceitável e, muitas vezes, mais organizado.

| Evento | Dispara quando |
|---|---|
| `status.updated` | O status de uma sessão de KYC ou KYB muda. O que você quase certamente quer |
| `data.updated` | Os dados de verificação são editados após a criação - um revisor corrigindo um campo |
| `user.status.updated` | Um usuário consolidado muda entre ACTIVE, FLAGGED e BLOCKED |
| `user.data.updated` | O perfil, contadores ou identificadores de um usuário consolidado mudam |
| `business.status.updated` | Uma empresa consolidada muda de status |
| `business.data.updated` | Os dados de uma empresa consolidada mudam |
| `transaction.created` | Uma transação é criada e seu veredito inicial está pronto |
| `transaction.status.updated` | O status de uma transação muda posteriormente |
| `travel_rule.status.updated` | O status de uma troca da Travel Rule muda |

> **Note:** Não existe `session.status.updated` nem `kyc.completed`. Se você se inscreveu em um
> nome que não está nesta lista, você não vai receber nada - e isso vai parecer
> exatamente uma falha de entrega. Verifique o nome primeiro.

## O que o seu endpoint deve fazer

- **Verifique a assinatura antes de qualquer outra coisa.** Faça o HMAC sobre o corpo **bruto** da requisição - nunca sobre uma versão re-serializada do JSON já convertido, porque transformar de volta em string muda os bytes e a assinatura não vai corresponder. Use uma comparação de tempo constante.
- **Retorne um 2xx rápido.** Faça o trabalho pesado de forma assíncrona, depois de já ter respondido.
- **Seja idempotente.** Use como chave o id do evento, ou a combinação id da sessão + status + tipo de webhook. Tentativas repetidas e duplicatas acontecem.
- **Trate todo status que importa para você**, incluindo os que chegam bem depois do onboarding - uma sessão aprovada pode mais tarde passar para In Review através do [monitoramento contínuo de AML](https://help.didit.me/pt-BR/aml-screening/ongoing-monitoring).
- **Somente HTTPS.** Endpoints em HTTP simples não são suportados.

## Novas tentativas

Em respostas 5xx ou 404, a Didit tenta novamente duas vezes, após cerca de um minuto e depois quatro. Timeout de 5 segundos ou falha de conexão não tem nova tentativa automática. Use Reenviar em Entregas após corrigir; uma falha definitiva gera um alerta.

> **Warning:** Não presuma que todo webhook será recebido. Após uma interrupção, reenvie as entregas ou consulte a decisão de cada sessão cujo resultado não chegou.

## Atrás de um firewall ou WAF

A Didit entrega a partir do IP estático **18.203.201.92** com um user agent `DiditWebhook/2.0`. Se sua borda bloqueia clientes desconhecidos - a postura padrão do Cloudflare, por exemplo - libere esse IP para o hostname de recebimento, ou as entregas vão falhar antes de chegar ao seu código.

## Ainda não tem um backend?

Você ainda pode acompanhar os resultados manualmente na seção **Verifications** do console enquanto constrói um, ou usar um [link de verificação sem código](https://help.didit.me/pt-BR/integration/integration-options) enquanto isso.

## Próximos passos

- Quando um webhook não chega: [quando um webhook nunca chega](https://help.didit.me/pt-BR/integration/webhook-troubleshooting)
- Entenda o que cada status significa quando chega: [o que cada status de sessão significa](https://help.didit.me/pt-BR/verification-sessions/session-statuses)
- Referência técnica completa, incluindo exemplos de código para verificação de assinatura: [Webhooks](https://docs.didit.me/integration/webhooks)