Saltar al contenido principal
Los webhooks permiten que su aplicación reciba notificaciones automáticas cuando ocurren eventos en su cuenta de Truthlocks; por ejemplo, cuando se acuña una atestación, se rota una clave o falla una verificación. En lugar de sondear la API en busca de cambios, su servidor recibe una solicitud HTTP POST con los detalles del evento.

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

Use category.* 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

  1. En la consola del inquilino, vaya a Configuración > Webhooks.
  2. Haga clic en Agregar punto de conexión.
  3. Ingrese un nombre, su URL de destino HTTPS y seleccione los tipos de eventos que desea recibir.
  4. Haga clic en Crear.
La consola muestra su secreto de endpoint una vez. Cópielo inmediatamente; no podrá recuperarlo más tarde.

A través de la API

Request
Response

Listar puntos finales

Recuperar todos los endpoints de webhook para su inquilino:
Request
Consulte la referencia completa de la API para obtener detalles de la respuesta.

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:
Donde t es la marca de tiempo Unix y v1 es el resumen hexadecimal HMAC-SHA256. Pasos de verificación:
  1. Extraiga t (marca de tiempo) y v1 (firma) del encabezado.
  2. Rechace la solicitud si la marca de tiempo tiene más de 5 minutos de antigüedad.
  3. Concatene {timestamp}.{raw_request_body} para formar la cadena de firma.
  4. Calcule HMAC-SHA256 de la cadena de firma usando su secreto de punto final.
  5. Compare el resumen calculado con v1 usando una comparación de tiempo constante.
Utilice siempre una función de comparación de tiempo constante (como crypto.timingSafeEqual o hmac.compare_digest) para evitar ataques de temporización.

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
Consulte la referencia de API de entregas de lista para obtener detalles de la respuesta.

Rotación de secretos

Si su secreto de webhook se ve comprometido, rótelo inmediatamente:
  1. En la consola del inquilino, vaya a Configuración > Webhooks y haga clic en el punto de conexión.
  2. Haga clic en Rotar secreto.
  3. Copie el nuevo secreto — el secreto antiguo deja de funcionar inmediatamente.
También puede rotar a través de la API:
Request

Probando webhooks

Envíe un evento de prueba para verificar que su endpoint esté funcionando:
  1. En la consola del inquilino, vaya a Configuración > Webhooks y haga clic en el punto de conexión.
  2. Haga clic en Enviar prueba.
  3. Se envía un evento webhook.test a su URL utilizando la tubería completa de firma y entrega.
A través de la API:
Request
Los campos 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 a risk.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

Responda a los webhooks rápidamente. Realice su procesamiento pesado de forma asíncrona después de devolver una respuesta 200 para evitar tiempos de espera y reintentos.
  • 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-Id para 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.