Obtener resultados de verificación con webhooks
Didit no te envía un correo cuando una verificación cambia de estado - configura un webhook para que tu backend se entere en el momento en que ocurre, y verifica la firma antes de confiar en él.
Un webhook es una solicitud HTTP que Didit envía a tu URL cuando algo cambia. Añade un destino en API & Webhooks, suscríbete a los eventos que quieras (no hay comodín, lista todos), guarda el secreto de firma, y verifica la firma antes de procesar nada.
Didit no te envía un correo cuando una sesión pasa a En revisión o Rechazada. Para enterarte en el momento en que un estado cambia, sin recargar la consola, configura un webhook: una URL en tu servidor a la que Didit envía la actualización automáticamente.
Los webhooks son el patrón de integración recomendado. Sondear el endpoint de decisión funciona como respaldo, pero es más lento, consume más solicitudes, y se pierde eventos que solo se entregan por webhook: ediciones de datos hechas por un revisor, cambios de estado de transacciones y cambios a nivel de entidad.
#Configurar uno
- Ve a API & Webhooks
En la Consola de Negocio, abre la aplicación para la que quieres recibir eventos, y luego ve a API & Webhooks.
- Añade un destino
Dale una etiqueta, la URL HTTPS pública de tu endpoint, y elige los eventos que quieras recibir: como mínimo, cambios de estado de sesión.
- Guarda el secreto de firma
El destino te muestra un secreto una sola vez. Guárdalo: tu servidor lo usa para confirmar que una solicitud viene realmente de Didit y no de un impostor. Pasos completos de verificación: Signature verification.
- Pruébalo
Usa Try Webhook en la misma página para enviar un evento de prueba completamente formado (escenarios de aprobado, rechazado, en revisión, KYB, entidad y transacción) a tu endpoint. Puedes validar tu integración así sin ejecutar una verificación real.
- Add destination registra la URL a la que Didit publica los resultados.
- Verifica cada entrega contra este secreto de firma antes de confiar en ella.
- Elige qué eventos recibe un destino.
- Test Webhook envía un payload de muestra para que puedas confirmar que tu endpoint lo acepta.
#Los eventos a los que puedes suscribirte
No hay comodín: lista cada familia de eventos que quieras. Repartirlos entre varios destinos está bien y a menudo es más limpio.
| Evento | Se dispara cuando |
|---|---|
status.updated | El estado de una sesión de KYC o KYB cambia. El que casi con toda seguridad quieres |
data.updated | Se edita un dato de verificación después de crearse: un revisor corrigiendo un campo |
user.status.updated | Un usuario consolidado pasa entre ACTIVE, FLAGGED y BLOCKED |
user.data.updated | Cambian el perfil, los contadores o los identificadores de un usuario consolidado |
business.status.updated | Cambia el estado de una empresa consolidada |
business.data.updated | Cambian los datos de una empresa consolidada |
transaction.created | Se crea una transacción y su veredicto inicial está listo |
transaction.status.updated | El estado de una transacción cambia después |
travel_rule.status.updated | Cambia el estado de un intercambio de Travel Rule |
No existe session.status.updated ni kyc.completed. Si te suscribiste a un
nombre que no está en esta lista, no recibirás nada, y parecerá exactamente un
fallo de entrega. Comprueba primero el nombre.
#Qué debe hacer tu endpoint
- Verificar la firma antes que nada. Aplica HMAC al cuerpo en bruto de la solicitud, nunca a una versión re-serializada del JSON analizado, porque volver a convertirlo a cadena cambia los bytes y la firma no coincidirá. Usa una comparación en tiempo constante.
- Devolver un 2xx rápido. Haz el trabajo pesado de forma asíncrona, después de responder.
- Ser idempotente. Usa como clave el id del evento, o el id de sesión más el estado más el tipo de webhook. Los reintentos y los duplicados ocurren.
- Gestionar cada estado que te importe, incluidos los que llegan mucho después del alta: una sesión aprobada puede pasar más tarde a En revisión a través de la monitorización AML continua.
- Solo HTTPS. Los endpoints HTTP simples no son compatibles.
#Reintentos
Ante un 5xx, un 404, un timeout, o un fallo de conexión, Didit reintenta dos veces:
- Primer reintento aproximadamente 1 minuto después del fallo inicial
- Segundo reintento aproximadamente 4 minutos después de ese
Después de eso, la entrega se descarta. Cada intento se registra por separado en la pestaña Deliveries del destino, así que puedes ver exactamente qué pasó en lugar de adivinar.
Dos reintentos en cinco minutos no son una cola duradera. Si tu endpoint estuvo caído una hora, esos eventos han desaparecido. Reconcilia al arrancar sondeando el endpoint de decisión para las sesiones de las que no tengas un estado final: los webhooks son la vía rápida, no la única vía.
#Detrás de un firewall o un WAF
Didit entrega desde la IP estática 18.203.201.92 con un user agent DiditWebhook/2.0. Si tu borde bloquea clientes desconocidos (la postura por defecto de Cloudflare, por ejemplo), permite esa IP para el hostname receptor, o las entregas fallarán antes de llegar a tu código.
#¿Todavía no tienes un backend?
Puedes seguir vigilando los resultados manualmente en la sección Verifications de la consola mientras construyes uno, o usar un enlace de verificación sin código mientras tanto.
#Próximos pasos
- Cuando un webhook no llega: cuando un webhook nunca llega
- Entiende qué significa cada estado una vez que llega: qué significa cada estado de sesión
- Referencia técnica completa, incluidos ejemplos de código de verificación de firma: Webhooks