Recebendo resultados de verificação com webhooks
A Didit não envia e-mail quando uma verificação muda de status - configure um webhook para que seu backend saiba disso no exato momento em que acontece, e verifique a assinatura antes de confiar nela.
Um webhook é uma requisição HTTP que a Didit envia para a sua URL quando algo muda. Adicione um destino em API & 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.
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
- Go to API & Webhooks
No Business Console, abra a aplicação para a qual você quer receber eventos e vá em API & Webhooks.
- Add a destination
Dê um nome a ele, informe a URL HTTPS pública do seu endpoint, e escolha os eventos que você quer receber - no mínimo, mudanças de status de sessão.
- Save the signing secret
O destino mostra um secret uma única vez. Guarde-o - seu servidor o usa para confirmar que uma requisição realmente veio da Didit e não de um impostor. Passo a passo completo de verificação: Verificação de assinatura.
- Test it
Use Try Webhook na mesma página para enviar um evento de teste completamente formado - cenários de approved, declined, in review, KYB, entity e transaction - para o seu endpoint. Você pode validar sua integração dessa forma sem executar uma verificação de verdade.
- Add destination registra a URL para a qual a Didit envia os resultados.
- Verifique toda entrega com este signing secret antes de confiar nela.
- Escolha quais eventos um destino recebe.
- Test Webhook envia um payload de exemplo para você confirmar que seu endpoint o aceita.
#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 |
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.
- Somente HTTPS. Endpoints em HTTP simples não são suportados.
#Novas tentativas
Em caso de 5xx, 404, timeout, ou falha de conexão, a Didit tenta novamente duas vezes:
- Primeira tentativa cerca de 1 minuto após a falha inicial
- Segunda tentativa cerca de 4 minutos depois disso
Depois disso, a entrega é descartada. Toda tentativa é registrada separadamente na aba Deliveries do destino, então você pode ver exatamente o que aconteceu, em vez de adivinhar.
Duas tentativas em cinco minutos não é uma fila durável. Se o seu endpoint ficar fora do ar por uma hora, esses eventos se perdem. Reconcilie na inicialização fazendo polling no endpoint de decisão para as sessões cujo status final você não tem - webhooks são o caminho rápido, não o único caminho.
#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 enquanto isso.
#Próximos passos
- Quando um webhook não chega: quando um webhook nunca chega
- Entenda o que cada status significa quando chega: o que cada status de sessão significa
- Referência técnica completa, incluindo exemplos de código para verificação de assinatura: Webhooks