Webhooks KYT: eventos de transacciones y firma HMAC

Transaction Monitoring emite tres eventos de webhook que, en conjunto, cubren el ciclo de vida completo de una transacción, además de un cuarto opcional que anuncia nuevas sugerencias de reglas. Todos usan la infraestructura estándar de webhooks de Didit con firma HMAC-SHA256. Consulta la referencia de webhooks para ver destinos, firma y pruebas.

Catálogo de eventos

Evento	Cuándo se dispara
`transaction.created`	Se creó una nueva transacción y se completó su evaluación inicial. También se dispara para las transacciones entrantes que Didit crea por ti: un registro sunrise de Travel Rule posterior a un depósito, una consulta `TRP` entrante o una transferencia a través de la red `INTERNAL` desde otro cliente de Didit.
`transaction.status.updated`	Cambió el estado de la transacción. El cambio puede venir de la revisión de un analista, de la resolución de una sesión de remediación o de la acción de una regla cuando Didit vuelve a evaluar tus reglas tras una transición de Travel Rule (por ejemplo, después de una prueba de propiedad de la wallet). El cambio de estado que aplica tu `timeout_outcome` cuando una transferencia expira no envía este evento; en su lugar, reacciona a `travel_rule.status.updated` con `EXPIRED`.
`travel_rule.status.updated`	Un intercambio de Travel Rule cambió de estado. Se dispara en transferencias salientes y entrantes (el tramo entrante por el rail `INTERNAL`, los registros sunrise y las consultas `TRP` entrantes) e incluye la transición `NOT_APPLICABLE` por debajo del umbral. En una transacción que crea Didit, estos eventos se envían después de su `transaction.created`.
`transaction_rule_suggestions.created`	Una ejecución de sugerencias de reglas propuso nuevos cambios de reglas para tu aplicación. Solo se dispara cuando activas Webhook en la configuración de notificaciones de sugerencias de reglas, y solo para las ejecuciones que crearon sugerencias.

Los eventos a nivel de entidad (user.status.updated, business.status.updated) también pueden dispararse como consecuencia de la actividad de las transacciones. Consulta los webhooks de entidades.

Las aplicaciones de sandbox no emiten los webhooks transaction.created ni transaction.status.updated. Para probar esos eventos, usa una aplicación del entorno de producción o API & Webhooks → Try Webhook en la consola. Los intercambios de Travel Rule en sandbox sí emiten webhooks travel_rule.status.updated con environment: sandbox; usa el Didit Test VASP para probar un intercambio antes de pasar a producción.

Envoltorio

Los webhooks de Didit usan un cuerpo plano: los campos del evento están en el nivel superior, junto a los campos del envoltorio, y no hay ningún objeto data anidado. Cada entrega incluye:

Campo	Descripción
`webhook_type`	El nombre del evento, por ejemplo `transaction.created`.
`event_id`	Identificador estable del evento. Se reutiliza el mismo `event_id` en los reintentos, así que úsalo para eliminar duplicados.
`timestamp` / `created_at`	Segundos desde la época Unix cuando se envió la entrega.
`application_id`	La aplicación a la que pertenece el evento.
`environment`	`live` o `sandbox`.

Estructura de los payloads

`transaction.created` y `transaction.status.updated`

Ambos eventos comparten un mismo payload: un resumen compacto más el bloque action_required (o null):

{
  "webhook_type": "transaction.created",
  "event_id": "9c0c8b8a-1111-4222-9333-666666666666",
  "timestamp": 1774970000,
  "created_at": 1774970000,
  "application_id": "11111111-2222-3333-4444-555555555555",
  "environment": "live",
  "transaction_id": "9c7d2a30-...",
  "txn_id": "tx-0001",
  "status": "IN_REVIEW",
  "score": 65,
  "severity": "MEDIUM",
  "amount": "500.00",
  "currency": "EUR",
  "direction": "OUTBOUND",
  "action_required": null
}

El payload es deliberadamente escueto: al recibirlo, obtén el registro completo con GET /v3/transactions/{transaction_id}/. Este endpoint devuelve todos los detalles (partes, rule_runs, provider_results, travel_rule, cost_breakdown, decision_reason_code), incluido por qué cambió el estado.

`transaction_rule_suggestions.created`

Este evento se refiere a tu conjunto de reglas, no a una transacción concreta, por lo que no incluye ningún ID de transacción. Nunca contiene datos personales: solo IDs, tipos, títulos y recuentos de las sugerencias.

{
  "webhook_type": "transaction_rule_suggestions.created",
  "run_id": "5b2f0c1e-0000-0000-0000-000000000000",
  "open_count": 3,
  "suggestions": [
    {
      "suggestion_id": "9a7d3e22-0000-0000-0000-000000000000",
      "kind": "...",
      "title": "...",
      "rule_id": "...",
      "expected_impact": {}
    }
  ]
}

Campo	Descripción
`run_id`	La ejecución que generó las nuevas sugerencias.
`open_count`	Cuántas sugerencias quedan abiertas para la aplicación después de esta ejecución.
`suggestions[]`	Las sugerencias que creó esta ejecución, cada una con `suggestion_id`, `kind`, `title`, `rule_id` (null cuando la sugerencia propone una regla nueva) y `expected_impact`.

Los campos habituales del envoltorio (event_id, timestamp, application_id, environment) se añaden al cuerpo.

`travel_rule.status.updated`

{
  "webhook_type": "travel_rule.status.updated",
  "event_id": "9c0c8b8a-1111-4222-9333-777777777777",
  "timestamp": 1774970000,
  "created_at": 1774970000,
  "application_id": "11111111-2222-3333-4444-555555555555",
  "environment": "live",
  "transaction_id": "22222222-3333-4444-5555-666666666666",
  "txn_id": "trv-2026-07-05-001",
  "travel_rule_status": "COMPLETED",
  "rail": "INTERNAL",
  "direction": "OUTBOUND"
}

Se dispara en cada transición, incluido el paso a FINISHED, CANCELLED o EXPIRED; una vez que una transferencia llega a uno de esos estados, no se envían más eventos de Travel Rule para ella. Un evento puede repetir el estado del anterior, por ejemplo cuando un reenvío vuelve a no encontrar ningún rail y la transferencia permanece en COUNTERPARTY_VASP_NOT_FOUND. rail es INTERNAL, TRP, GTR, TRUST, VERIFYVASP, SYGNA, EMAIL, TEST_VASP (una transferencia de sandbox a la que respondió el Didit Test VASP, que además incluye test_vasp: true y test_vasp_scenario), o "" mientras no se haya seleccionado ningún rail (siempre "" en los registros sunrise). Al crear una transacción, en un registro sunrise, en una consulta TRP entrante o en el tramo entrante por el rail INTERNAL, Didit envía primero transaction.created y, después, los eventos travel_rule.status.updated de la transacción. Una regla que cambie el estado de la transacción durante ese paso también puede enviar transaction.status.updated antes de transaction.created. Un registro sunrise que se asocia a una transacción de depósito que ya creaste no envía transaction.created. Cada webhook se entrega y se reintenta por separado, así que un evento reintentado puede llegar después de uno posterior: usa transaction_id como clave en tu handler y vuelve a leer la transacción cuando necesites su estado actual.

Ejemplos de recorridos de estado

Aprobación simple

transaction.created (APPROVED, score 0)

Revisión y luego aprobación

transaction.created (IN_REVIEW, score 65)
...analyst reviews...
transaction.status.updated (status: APPROVED)

Verificación adicional (step-up)

transaction.created (AWAITING_USER, action_required.type: verification_session)
...user completes the biometric re-check...
transaction.status.updated (status: APPROVED, action_required: null)

Transferencia con Travel Rule

transaction.created (APPROVED)
travel_rule.status.updated (AWAITING_COUNTERPARTY, rail: EMAIL)
...counterparty accepts the pickup...
travel_rule.status.updated (COMPLETED)
...you broadcast on-chain and PATCH the hash...
travel_rule.status.updated (FINISHED)

Los dos primeros eventos provienen de la misma solicitud, y transaction.created se pone en cola primero; cada webhook se entrega por separado, así que no dependas del orden de llegada. Una transferencia enviada a través de TRUST nunca recibe un evento COMPLETED, porque TRUST no devuelve nada que Didit pueda leer: permanece en AWAITING_COUNTERPARTY hasta que vence el plazo de confirmación y termina en EXPIRED. A través de GTR, VerifyVASP y Sygna Bridge, Didit lee la respuesta de la contraparte desde la red y el evento la refleja.

Verificación de firma

Cada entrega se firma con HMAC-SHA256 usando el secreto compartido del destino e incluye tres encabezados de firma más una marca de tiempo:

Encabezado	Esquema
`X-Signature-V2`	HMAC sobre el JSON canónico (claves ordenadas, Unicode conservado): recomendado.
`X-Signature`	HMAC sobre el JSON canónico con escape ASCII (heredado).
`X-Signature-Simple`	HMAC sobre `"{timestamp}:{session_id}:{status}:{webhook_type}"`: obsoleto. Los payloads de transacciones no incluyen `session_id`, así que esto firma `"{timestamp}::{status}:{webhook_type}"`: no identifica ni la transacción ni su importe o puntuación. Un payload `travel_rule.status.updated` tampoco incluye `status`, así que firma `"{timestamp}:::travel_rule.status.updated"`. Verifica con `X-Signature-V2` y consulta el aviso de obsolescencia.
`X-Timestamp`	Segundos de época Unix: rechaza las entregas con más de 5 minutos de antigüedad.

import { createHmac, timingSafeEqual } from 'crypto';

function verify(rawBody: string, signatureV2: string, secret: string) {
  const canonical = JSON.stringify(
    Object.keys(JSON.parse(rawBody)).sort()
      .reduce((acc, k) => ({ ...acc, [k]: JSON.parse(rawBody)[k] }), {})
  );
  const expected = createHmac('sha256', secret).update(canonical).digest('hex');
  return timingSafeEqual(Buffer.from(signatureV2), Buffer.from(expected));
}

Consulta la referencia de webhooks para ver el código de verificación completo, incluida la comprobación de vigencia de la marca de tiempo.

Reintentos y garantías de entrega

Ante un 5xx, un 404, un tiempo de espera agotado o un fallo de conexión, Didit reintenta hasta 2 veces: aproximadamente 1 minuto después del fallo inicial y, después, unos 4 minutos más tarde.
Las entregas reintentadas reutilizan el mismo event_id: úsalo para eliminar duplicados en tu handler.
Tras el último fallo, la entrega de ese evento se detiene y se notifica a tu organización; los destinos nunca se desactivan de forma silenciosa.
Devuelve un 2xx rápidamente (encola y luego procesa): las confirmaciones lentas pueden provocar tiempos de espera agotados y entregas duplicadas.

Idempotencia

Procesa cada webhook exactamente una vez guardando event_id en tu propio almacén de deduplicación. Es posible que el mismo evento se vuelva a entregar si tu endpoint confirma lentamente o se desconecta a mitad de la solicitud.

Suscripción

curl -X POST https://verification.didit.me/v3/webhook/destinations/ \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "label": "TM events",
    "url": "https://yourapp.com/webhooks/didit-tm",
    "subscribed_events": [
      "transaction.created",
      "transaction.status.updated",
      "travel_rule.status.updated"
    ]
  }'

Próximos pasos

Referencia de webhooks

Destinos, firma y reintentos.

Estados

Máquina de estados completa.

Guía de integración

Gestión de webhooks en producción.

Primeros pasos

Funciones

Referencia

Consola

Webhooks KYT: eventos de transacciones y firma HMAC

Catálogo de eventos

Envoltorio

Estructura de los payloads

`transaction.created` y `transaction.status.updated`

`transaction_rule_suggestions.created`

`travel_rule.status.updated`

Ejemplos de recorridos de estado

Aprobación simple

Revisión y luego aprobación

Verificación adicional (step-up)

Transferencia con Travel Rule

Verificación de firma

Reintentos y garantías de entrega

Idempotencia

Suscripción

Próximos pasos

Referencia de webhooks

Estados

Guía de integración

​Catálogo de eventos

​Envoltorio

​Estructura de los payloads

​transaction.created y transaction.status.updated

​transaction_rule_suggestions.created

​travel_rule.status.updated

​Ejemplos de recorridos de estado

​Aprobación simple

​Revisión y luego aprobación

​Verificación adicional (step-up)

​Transferencia con Travel Rule

​Verificación de firma

​Reintentos y garantías de entrega

​Idempotencia

​Suscripción

​Próximos pasos

Referencia de webhooks

Estados

Guía de integración

Catálogo de eventos

Envoltorio

Estructura de los payloads

`transaction.created` y `transaction.status.updated`

`transaction_rule_suggestions.created`

`travel_rule.status.updated`

Ejemplos de recorridos de estado

Aprobación simple

Revisión y luego aprobación

Verificación adicional (step-up)

Transferencia con Travel Rule

Verificación de firma

Reintentos y garantías de entrega

Idempotencia

Suscripción

Próximos pasos