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.
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
- Programadores → Webhooks
Abra a aplicação e o ambiente Live ou Sandbox corretos, depois Programadores e Webhooks.
- 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.
- 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.
- 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.
#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 |
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.
- 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.
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 entretanto.
#Próximos passos
- Quando um webhook não chega: quando um webhook nunca chega
- Perceber o que cada estado significa quando chega: o que cada estado de sessão significa
- Referência técnica completa, incluindo exemplos de código para verificação de assinatura: Webhooks
Continua com dúvidas? Fale com uma pessoa.
Inclua o ID da sua organização e o ID da sessão sobre a qual pergunta.