Cómo funciona
1
Registrar un endpoint
Añada un punto final de webhook en Configuración > Webhooks en la consola del inquilino. Proporcione una URL HTTPS accesible públicamente y elija qué tipos de eventos desea recibir.
2
Recibir eventos
Cuando ocurre un evento coincidente, Truthlocks envía una solicitud HTTP POST a su URL con una carga JSON que describe el evento.
3
Verificar la firma
Cada solicitud incluye una firma HMAC-SHA256 en el encabezado
X-Truthlocks-Signature. Verifíquela usando el secreto del endpoint para confirmar que la solicitud provino de Truthlocks.4
Responder con 200
Devuelve un código de estado HTTP
200 para acusar recibo. Si tu endpoint falla o excede el tiempo de espera, Truthlocks reintenta con retroceso exponencial.Tipos de eventos
Los eventos se agrupan en categorías. Puede suscribirse a eventos individuales o usar un comodín (attestation.*) para recibir todos los eventos de una categoría.
Filtros comodín
Usecategory.* para suscribirse a cada evento de una categoría. Por ejemplo, attestation.* coincide con attestation.created, attestation.revoked, attestation.expired y attestation.superseded.
Límites de endpoint por plan
El número de puntos finales de webhook que puede crear depende de su nivel de plan:
¿Necesita más endpoints? Póngase en contacto con su gerente de cuenta o actualice su plan en Configuración > Facturación.
Creación de un endpoint
- En la consola del inquilino, vaya a Configuración > Webhooks.
- Haga clic en Agregar punto de conexión.
- Ingrese un nombre, su URL de destino HTTPS y seleccione los tipos de eventos que desea recibir.
- Haga clic en Crear.
A través de la API
Request
Response
Listar puntos finales
Recuperar todos los endpoints de webhook para su inquilino:Request
Verificación de firmas
Cada solicitud de webhook incluye un encabezado de firma para verificación. Siempre verifique las firmas antes de procesar los eventos. Formato de firma:t es la marca de tiempo Unix y v1 es el resumen hexadecimal HMAC-SHA256.
Pasos de verificación:
- Extraiga
t(marca de tiempo) yv1(firma) del encabezado. - Rechace la solicitud si la marca de tiempo tiene más de 5 minutos de antigüedad.
- Concatene
{timestamp}.{raw_request_body}para formar la cadena de firma. - Calcule HMAC-SHA256 de la cadena de firma usando su secreto de punto final.
- Compare el resumen calculado con
v1usando una comparación de tiempo constante.
Encabezados de la solicitud
Cada entrega de webhook incluye estos encabezados:Comportamiento de reintento
Si su endpoint devuelve un código de estado que no sea 2xx o no responde en 5 segundos, Truthlocks reintenta la entrega con retroceso exponencial:
Los retrasos incluyen hasta un 30% de fluctuación. Después de 8 intentos totales (1 inicial + 7 reintentos), la entrega se marca como fallida.
Puede ver los intentos de entrega y los detalles de fallas en Configuración > Webhooks haciendo clic en un punto final, o consultarlos a través de la API:
Request
Rotación de secretos
Si su secreto de webhook se ve comprometido, rótelo inmediatamente:- En la consola del inquilino, vaya a Configuración > Webhooks y haga clic en el punto de conexión.
- Haga clic en Rotar secreto.
- Copie el nuevo secreto — el secreto antiguo deja de funcionar inmediatamente.
Request
Probando webhooks
Envíe un evento de prueba para verificar que su endpoint esté funcionando:- En la consola del inquilino, vaya a Configuración > Webhooks y haga clic en el punto de conexión.
- Haga clic en Enviar prueba.
- Se envía un evento
webhook.testa su URL utilizando la tubería completa de firma y entrega.
Request
event_type y payload son opcionales; por defecto, son webhook.test y una carga útil de estado básica si se omiten.
Notificaciones de señales de riesgo
Puede recibir notificaciones de webhook en tiempo real cada vez que se crea una señal de riesgo por cualquiera de las cinco rutas de detección del Firewall de Identidad Antifraude — ingesta directa, normalización de eventos, escaneo de deepfakes, detección de ATO y puntuación de velocidad. Suscríbase arisk.signal.* para recibir todos los eventos de señales de riesgo, o suscríbase a risk.signal.created o risk.signal.escalated individualmente.
Carga útil de ejemplo
Respuesta a señales de riesgo
Utilice webhooks de señales de riesgo para activar respuestas automatizadas —bloquear una sesión de usuario, notificar a su equipo de seguridad o escalar a un caso de fraude— sin sondear la API.Los webhooks de señal de riesgo se activan para las señales creadas por las cinco rutas de detección. El campo
signal_source en la carga útil le indica qué ruta generó la señal: external, event_normalization, deepfake, ato o velocity.Mejores prácticas
- Verifique cada firma. Nunca omita la verificación de la firma, incluso en desarrollo.
- Use una cola de mensajes. Ponga en cola los eventos entrantes y procéselos en un trabajador para evitar bloquear la respuesta HTTP.
- Manejar duplicados. Use el encabezado
X-Truthlocks-Event-Idpara deduplicar eventos en caso de reintentos. - Monitorear fallos de entrega. Revise la pestaña de entregas en la consola regularmente para detectar entregas fallidas o muertas.
- Mantenga los secretos seguros. Almacene su secreto de webhook en variables de entorno, no en el código fuente.

