# Obter resultados de verificação com webhooks

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

A Didit não te envia e-mail quando uma verificação muda de estado - configura um webhook para o backend saber no momento, e verifica a assinatura.

Um webhook é um pedido HTTP que a Didit envia para o teu URL quando algo muda.
Adiciona um destino em **Programadores → Webhooks**, subscreve os eventos que
queres - não há **wildcard**, lista cada um - guarda o segredo de assinatura, e
verifica a assinatura antes de processares seja o que for.

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

A Didit não te envia um e-mail quando uma sessão passa para **In Review** ou **Declined**. Para saberes no momento em que um estado muda, sem teres de atualizar a consola, configura um webhook - um URL no teu servidor para o qual a Didit envia a atualização automaticamente.

Os webhooks são o padrão de integração **recomendado**. Fazer polling ao endpoint de decisão funciona como alternativa, mas é mais lento, custa mais pedidos, e falha eventos que só são entregues por webhook - edições de dados feitas por um revisor, alterações de estado de transações, e alterações ao nível de entidade.

## Configurar um

1. **Programadores → Webhooks**

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

2. **Adicione um endpoint**

   Prima Adicionar endpoint, indique o URL HTTPS e um nome e selecione os eventos. Mantenha a versão recomendada v3, exceto para manter uma integração antiga. Reveja e confirme.

3. **Guarda o segredo de assinatura**

   Cada endpoint tem o seu próprio segredo de assinatura oculto. Prima Revelar e confirme a identidade; volta a ficar oculto em 60 segundos. Guarde-o na configuração do servidor. Contacte o suporte se Revelar estiver desativado. [Programadores → 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 na consola Didit com eventos subscritos e histórico de entregas](https://help.didit.me/screenshots/webhooks-light.webp)

*Cada destino tem os seus próprios eventos subscritos, segredo de assinatura, e registo de entregas.*

## Os eventos a que te podes subscrever

Não há **wildcard** - lista cada família de eventos que queres. Distribuí-los por vários destinos é uma opção válida e muitas vezes mais organizada.

| Evento | Dispara quando |
|---|---|
| `status.updated` | O estado de uma sessão de KYC ou KYB muda. O que quase de certeza queres |
| `data.updated` | Os dados de verificação são editados depois da criação - um revisor a corrigir um campo |
| `user.status.updated` | Um utilizador consolidado muda entre ACTIVE, FLAGGED e BLOCKED |
| `user.data.updated` | O perfil, contadores ou identificadores de um utilizador consolidado mudam |
| `business.status.updated` | Uma empresa consolidada muda de estado |
| `business.data.updated` | Os dados de uma empresa consolidada mudam |
| `transaction.created` | Uma transação é criada e o seu veredito inicial está pronto |
| `transaction.status.updated` | O estado de uma transação muda depois disso |
| `travel_rule.status.updated` | O estado de uma troca do Travel Rule muda |

> **Note:** Não existe `session.status.updated` nem `kyc.completed`. Se te subscreveste a
> um nome que não está nesta lista, não vais receber nada - e vai parecer
> exatamente uma falha de entrega. Verifica primeiro o nome.

## O que o teu endpoint deve fazer

- **Verifica a assinatura antes de tudo o resto.** Faz o HMAC ao corpo do pedido **em bruto** - nunca a uma versão re-serializada do JSON analisado, porque voltar a converter em string muda os bytes e a assinatura não vai corresponder. Usa uma comparação em tempo constante.
- **Devolve um 2xx rapidamente.** Faz o trabalho pesado de forma assíncrona, depois de teres respondido.
- **Sê idempotente.** Usa como chave o id do evento, ou o id da sessão + estado + tipo de webhook. Repetições e duplicados acontecem.
- **Trata cada estado que te interessa**, incluindo os que chegam muito depois da integração - uma sessão aprovada pode mais tarde passar a In Review através da [monitorização AML contínua](https://help.didit.me/pt-PT/aml-screening/ongoing-monitoring).
- **Só HTTPS.** Endpoints em HTTP simples não são suportados.

## Repetições

Nas respostas 5xx ou 404, a Didit tenta novamente duas vezes, após cerca de um minuto e depois quatro. Um tempo limite de 5 segundos ou falha de ligação não é repetido automaticamente. Use Reenviar em Entregas após corrigir; uma falha definitiva gera um alerta.

> **Warning:** Não presuma que todos os webhooks serão recebidos. Após uma interrupção, reenvie as entregas ou consulte a decisão de cada sessão cujo resultado não recebeu.

## Atrás de uma firewall ou WAF

A Didit entrega a partir do IP estático **18.203.201.92** com um user agent `DiditWebhook/2.0`. Se o teu edge bloquear clientes desconhecidos - a postura por defeito do Cloudflare, por exemplo - permite esse IP para o nome do anfitrião recetor, ou as entregas vão falhar antes de chegarem ao teu código.

## Ainda não tens um backend?

Podes continuar a acompanhar os resultados manualmente na secção **Verificações** da consola enquanto constróis um, ou usar um [link de verificação sem código](https://help.didit.me/pt-PT/integration/integration-options) entretanto.

## Próximos passos

- Quando um webhook não chega: [quando um webhook nunca chega](https://help.didit.me/pt-PT/integration/webhook-troubleshooting)
- Perceber o que cada estado significa quando chega: [o que cada estado de sessão significa](https://help.didit.me/pt-PT/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)