Introducción

Los webhooks te permiten recibir notificaciones automáticas cada vez que ocurre un evento importante en Trazo. En lugar de realizar un polling a la API para verificar si hay nuevos eventos, los webhooks permiten enviar datos directamente al endpoint que definas en tiempo real.

En Trazo, hemos implementado webhooks para una variedad de eventos clave que pueden ocurrir durante la operación. Los principales eventos que actualmente soportamos son:

• Cobros: Notificaciones cuando se completa un cobro exitoso o cuando hay actualizaciones en el estado de un cobro.

• Dispersiones: Alertas cuando se confirma una dispersión, permitiéndote mantener un seguimiento preciso de los movimientos de dinero, o cuando hay actualizaciones en el estado.

• Suscripciones: Notificaciones cuando una suscripción se activa, se vence, se cancela o completa su ciclo.

• Equipo: Eventos relacionados con los límites de efectivo o novedades del equipo que se encuentra operando en el día.

Todo lo que se explica en esta sección (encabezados, firma, reintentos y el event_id) aplica por igual a cualquier tipo de evento.

Encabezados

Encabezado	Contenido	Uso
Authorization	Bearer {integration_key}	Identifica que la solicitud proviene de Trazo.
X-Trazo-Signature	timestamp={timestamp},signature={firma}	Valida el origen y la integridad del mensaje. Es el encabezado que debes verificar siempre.
X-Trazo-Event-Id	Identificador único del evento	Detectar reintentos: es el mismo en los 3 intentos de una misma entrega.
X-Trazo-Event-Attempt	1, 2 o 3	Indica qué intento de la entrega estás recibiendo.
Content-Type	application/json	Formato del cuerpo de la solicitud.
custom_header	El que hayas configurado	Opcional. Solo se envía si se configuró uno para el comercio.

Seguridad y autenticación

Cada solicitud que enviamos incluye dos mecanismos de validación. Recomendamos verificar ambos en el endpoint antes de procesar el evento.

El primero es el encabezado Authorization, que viaja con la integration_key. Permite descartar rápidamente cualquier solicitud que no provenga de Trazo.

El segundo es el encabezado X-Trazo-Signature, una firma calculada sobre el contenido del mensaje usando el auth_key como secreto. A diferencia del Authorization, la llave con la que se calcula la firma nunca viaja en la solicitud, por lo que solo el sistema debe conocerla y puede verificarla. Esto permite confirmar que el contenido no fue alterado y que la solicitud no es la repetición de una anterior.

Si necesitas un encabezado adicional propio de su integración, debes solicitar el encabezado personalizado para el comercio, y Trazo lo enviará en cada solicitud junto con los anteriores.

Valida siempre la firma, no solo el Authorization. El integration_key viaja en cada solicitud, por lo que queda registrado en los logs, proxies y demás intermediarios por los que pase; la firma es la que realmente prueba el origen y la integridad del mensaje.

Validación de la firma

El encabezado X-Trazo-Signature tiene este formato:

timestamp=1754006400,signature=5257a869e7ecebeda32affa62cdca3fa66d9f7...

• timestamp: momento en que se generó la solicitud, en segundos desde epoch.

• signature: la firma, en hexadecimal.

Para validarla:

1. Toma el cuerpo de la solicitud exactamente como lo recibiste, sin parsear ni volver a serializar. Si tu framework lo convierte a objeto y luego lo serializas de nuevo para firmar, el resultado casi nunca es idéntico byte a byte al original (cambia el orden de las claves, los espacios) y la validación falla aunque el mensaje sea legítimo.

2. Concatena el timestamp y el cuerpo con un punto: {timestamp}.{body}.

3. Calcula el HMAC-SHA256 de esa cadena usando el auth_key como secreto.

4. Compara el resultado con signature, usando una comparación de tiempo constante (no un === directo sobre los strings).

5. Verifica que timestamp no tenga más de 5 minutos de antigüedad, para descartar la repetición de una solicitud capturada anteriormente.

const crypto = require("crypto");

function validarFirma(rawBody, signatureHeader, authKey) {
  if (!signatureHeader || !rawBody) return false;

  const partes = Object.fromEntries(
    signatureHeader.split(",").map((p) => p.split("="))
  );

  // 1. Validar existencia de campos
  if (!partes.timestamp || !partes.signature) return false;

  // 2. Validar vigencia del timestamp primero (evita calcular el HMAC si ya expiró)
  const vigente = Math.abs(Date.now() / 1000 - Number(partes.timestamp)) <= 300;
  if (!vigente) return false;

  // 3. Calcular el HMAC esperado
  const esperada = crypto
    .createHmac("sha256", authKey)
    .update(`${partes.timestamp}.${rawBody}`)
    .digest("hex");

  // 4. Comparación en tiempo constante
  if (partes.signature.length !== esperada.length) return false;

  return crypto.timingSafeEqual(
    Buffer.from(partes.signature),
    Buffer.from(esperada)
  );
}

Entrega y reintentos

Al enviar un evento esperamos hasta 15 segundos por la respuesta de tu endpoint.

Si tu endpoint responde con un error 5xx, volvemos a intentarlo hasta completar 3 intentos:

Intento	Cuándo
1º	Inmediato
2º	5 segundos después de la respuesta del intento anterior
3º	10 segundos después de la respuesta del intento anterior

Por ejemplo, si tu endpoint responde con un error 5xx cada vez:

Intento 1: 05:30:00  ->  500
Intento 2: 05:30:05  ->  500
Intento 3: 05:30:15  ->  500  ->  evento no entregado

No reintentamos cuando tu endpoint responde con un error 4xx ni cuando no responde dentro de los 15 segundos: en ambos casos damos el evento por no entregado.

Si tu endpoint necesita más de 15 segundos para procesar el evento, responde primero y procesa después. Una respuesta que llega tarde se descarta y el evento no se reintenta.

Cómo identificar un reintento

Cada evento tiene un identificador único, el event_id, que viaja tanto en el cuerpo como en el encabezado X-Trazo-Event-Id. Ese identificador es el mismo en los tres intentos, por lo que te permite reconocer que se trata del mismo evento y no de una notificación nueva.

Además, el encabezado X-Trazo-Event-Attempt indica el número de intento (1, 2 o 3).

Te recomendamos guardar el event_id de cada evento que proceses y descartar los que ya hayas visto. Esto es importante porque un evento puede llegarte repetido incluso cuando tu sistema lo procesó correctamente: si tu endpoint alcanza a registrar el cambio pero responde con un error 5xx (o si el error lo devuelve un intermediario), para Trazo la entrega falló y se intenta.

Ten en cuenta que dos eventos con el mismo identificador de referencia (por ejemplo, external_reference) y el mismo event.status no son necesariamente el mismo evento: el event_id es el único dato que lo determina.