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.
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
- Desenvolvedores → Webhooks
Abra a aplicação e o ambiente Live ou Sandbox corretos, depois Desenvolvedores e Webhooks.
- 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.
- 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.
- 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 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 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.
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 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
Ainda com dúvida? Fale com uma pessoa.
Inclua o ID da sua organização e o ID da sessão sobre a qual você está perguntando.