Obter resultados de verificação com webhooks
A Didit não te envia um e-mail quando uma verificação muda de estado - configura um webhook para que o teu backend saiba disso no momento em que acontece, e verifica a assinatura antes de confiares nela.
Um webhook é um pedido HTTP que a Didit envia para o teu URL quando algo muda. Adiciona um destino em API & 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
- Vai a API & Webhooks
Na Business Console, abre a aplicação para a qual queres receber eventos, depois vai a API & Webhooks.
- Adiciona um destino
Dá-lhe um nome, o URL HTTPS público do teu endpoint, e escolhe os eventos que queres receber - alterações de estado de sessão, no mínimo.
- Guarda o segredo de assinatura
O destino mostra-te um segredo uma única vez. Guarda-o - o teu servidor usa-o para confirmar que um pedido veio mesmo da Didit e não de um impostor. Passos completos de verificação: Verificação de assinatura.
- Testa-o
Usa Try Webhook na mesma página para enviar um evento de teste totalmente formado - cenários de aprovado, recusado, em revisão, KYB, entidade e transação - para o teu endpoint. Podes validar a tua integração desta forma sem correr uma verificação real.
- Add destination regista o URL para onde a Didit envia os resultados.
- Verifica cada entrega contra este segredo de assinatura antes de confiares nela.
- Escolhe que eventos um destino recebe.
- Test Webhook envia um payload de exemplo para confirmares que o teu endpoint o aceita.
#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
Num 5xx, num 404, num timeout, ou numa falha de ligação, a Didit repete duas vezes:
- Primeira repetição cerca de 1 minuto depois da falha inicial
- Segunda repetição cerca de 4 minutos depois dessa
Depois disso a entrega é abandonada. Cada tentativa é registada separadamente no separador Deliveries do destino, por isso consegues ver exatamente o que aconteceu em vez de adivinhar.
Duas repetições ao longo de cinco minutos não são uma fila duradoura. Se o teu endpoint estiver em baixo durante uma hora, esses eventos desaparecem. Reconcilia no arranque fazendo polling ao endpoint de decisão para as sessões sem estado terminal - os webhooks são o caminho rápido, não o único caminho.
#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