Com obtenir resultats de verificació amb webhooks
Didit no t'envia un correu quan una verificació canvia d'estat: configura un webhook perquè el teu backend se n'assabenti en el moment que passa, i verifica la signatura abans de confiar-hi.
Un webhook és una petició HTTP que Didit envia a la teva URL quan alguna cosa canvia. Afegeix una destinació a API & Webhooks, subscriu-te als esdeveniments que vulguis - no hi ha comodí, cal llistar-los tots - guarda el secret de signatura, i verifica la signatura abans de processar res.
Didit no t'envia cap correu quan una sessió passa a In Review o Declined. Per saber en el moment en què un estat canvia, sense haver de refrescar la consola, configura un webhook - una URL al teu servidor a la qual Didit envia l'actualització automàticament.
Els webhooks són el patró d'integració recomanat. Fer polling a l'endpoint de decisió funciona com a alternativa, però és més lent, costa més peticions, i es perd esdeveniments que només s'arriben a lliurar per webhook - edicions de dades fetes per un revisor, canvis d'estat de transaccions, i canvis a nivell d'entitat.
#Configurar-ne un
- Vés a API & Webhooks
A la Business Console, obre l'aplicació per a la qual vols rebre esdeveniments i després vés a API & Webhooks.
- Afegeix una destinació
Dona-li una etiqueta, la URL pública HTTPS del teu endpoint, i tria els esdeveniments que vulguis rebre - com a mínim, els canvis d'estat de sessió.
- Guarda el secret de signatura
La destinació et mostra un secret un sol cop. Guarda'l - el teu servidor el fa servir per confirmar que una petició realment ve de Didit i no d'un impostor. Passos complets de verificació: Verificació de signatura.
- Prova-ho
Fes servir Try Webhook a la mateixa pàgina per enviar un esdeveniment de prova completament format - escenaris d'aprovat, declinat, en revisió, KYB, entitat i transacció - al teu endpoint. D'aquesta manera pots validar la teva integració sense executar una verificació real.
- Add destination registra la URL a la qual Didit envia els resultats.
- Verifica cada lliurament contra aquest secret de signatura abans de confiar-hi.
- Tria quins esdeveniments rep una destinació.
- Test Webhook envia un payload d'exemple perquè puguis confirmar que el teu endpoint l'accepta.
#Els esdeveniments als quals et pots subscriure
No hi ha comodí - llista cada família d'esdeveniments que vulguis. Repartir-los entre diverses destinacions és vàlid i sovint queda més net.
| Esdeveniment | Es dispara quan |
|---|---|
status.updated | L'estat d'una sessió de KYC o KYB canvia. El que gairebé segur que vols |
data.updated | Les dades de verificació s'editen després de la creació - un revisor corregint un camp |
user.status.updated | Un usuari consolidat es mou entre ACTIVE, FLAGGED i BLOCKED |
user.data.updated | El perfil, els comptadors o els identificadors d'un usuari consolidat canvien |
business.status.updated | Una empresa consolidada canvia d'estat |
business.data.updated | Les dades d'una empresa consolidada canvien |
transaction.created | Es crea una transacció i el seu veredicte inicial ja està llest |
transaction.status.updated | L'estat d'una transacció canvia més endavant |
travel_rule.status.updated | L'estat d'un intercanvi de Travel Rule canvia |
No existeix cap session.status.updated ni kyc.completed. Si t'has subscrit a
un nom que no és en aquesta llista, no rebràs res - i semblarà exactament una
fallada de lliurament. Comprova el nom primer.
#Què hauria de fer el teu endpoint
- Verifica la signatura abans de qualsevol altra cosa. Calcula l'HMAC del cos en brut de la petició - mai d'una versió re-serialitzada del JSON parsejat, perquè tornar-lo a convertir en string canvia els bytes i la signatura no coincidirà. Fes servir una comparació de temps constant.
- Retorna un 2xx ràpidament. Fes la feina pesada de manera asíncrona, després de respondre.
- Sigues idempotent. Basa't en l'id de l'esdeveniment, o en id de sessió + estat + tipus de webhook. Els reintents i els duplicats passen.
- Gestiona cada estat que t'importi, incloent-hi els que arriben molt després de l'alta - una sessió aprovada pot passar més endavant a In Review a través del monitoratge continu d'AML.
- Només HTTPS. Els endpoints en HTTP simple no són compatibles.
#Reintents
Davant d'un 5xx, un 404, un timeout, o una fallada de connexió, Didit reintenta dues vegades:
- Primer reintent aproximadament 1 minut després de la fallada inicial
- Segon reintent aproximadament 4 minuts després d'això
Passat això, el lliurament es descarta. Cada intent queda registrat per separat a la pestanya Deliveries de la destinació, així que pots veure exactament què ha passat en lloc d'haver-ho d'endevinar.
Dos reintents en cinc minuts no és una cua durable. Si el teu endpoint està caigut durant una hora, aquells esdeveniments es perden. Reconcilia en arrencar fent polling a l'endpoint de decisió per a les sessions de les quals no tinguis cap estat terminal - els webhooks són el camí ràpid, no l'únic camí.
#Darrere d'un tallafoc o un WAF
Didit fa els lliuraments des de la IP estàtica 18.203.201.92 amb un user agent DiditWebhook/2.0. Si el teu edge bloqueja clients desconeguts - la postura per defecte de Cloudflare, per exemple - permet aquesta IP per al nom d'host receptor, o els lliuraments fallaran abans d'arribar al teu codi.
#Encara no tens backend?
Mentre en construeixes un, pots seguir supervisant els resultats manualment a la secció Verifications de la consola, o fer servir mentrestant un enllaç de verificació sense codi.
#Següents passos
- Quan un webhook no arriba: quan un webhook no arriba mai
- Entén què significa cada estat un cop arriba: què significa cada estat de sessió
- Referència tècnica completa, incloent-hi mostres de codi de verificació de signatura: Webhooks