Entrega y Reintentos

Reglas que debe cumplir tu endpoint receptor y cómo se comporta Zertiban cuando algo falla.

Esta sección define el comportamiento de entrega de webhooks por parte de Zertiban y los requisitos que debe cumplir el endpoint receptor para garantizar una integración estable, consistente y resiliente.

Zertiban implementa un modelo de entrega at-least-once: un mismo evento puede enviarse más de una vez en escenarios de reintento o fallos de red. Por este motivo, la deduplicación en el sistema receptor es obligatoria.

Reglas del endpoint receptor

El endpoint que recibe webhooks debe cumplir los siguientes requisitos funcionales y técnicos:

1. Verificación de firma. Cada webhook debe validarse con el mecanismo HMAC-SHA256 descrito en Verificación de Firma. No debe procesarse ningún evento cuya firma no sea válida.
2. Tiempo de respuesta. El endpoint debe responder 2xx en menos de 5 segundos. Si el procesamiento requiere más tiempo, responde 200 OK inmediatamente y continúa el procesamiento de forma asíncrona en segundo plano.
3. Deduplicación de eventos. Usa eventUuid como clave de idempotencia. Almacena los eventos ya procesados y descártalos si vuelven a recibirse para evitar efectos secundarios duplicados.
4. Sin redirecciones. El endpoint no debe devolver respuestas 3xx. Zertiban no sigue redirecciones bajo ningún concepto: cualquier redirección puede provocar la pérdida del evento.
5. Tolerancia a la entrega desordenada. Los eventos pueden llegar en un orden distinto al que ocurrieron. Usa el timestamp del body para detectar eventos obsoletos, tal y como se describe en Orden de los eventos y entrega desordenada.

Procesamiento asíncrono recomendado

Si la lógica de negocio asociada al webhook implica operaciones costosas o dependientes de sistemas externos (ERP, BBDD, emails, colas…), aplica el siguiente patrón:

1. Validar firma.
2. Persistir el evento en almacenamiento interno.
3. Responder 200 OK inmediatamente.
4. Procesar el evento de forma asíncrona mediante cola o worker.

Este enfoque mejora la resiliencia del sistema y evita bloqueos en la recepción de nuevos eventos.

Política de reintentos

Zertiban reintenta automáticamente la entrega de webhooks cuando no recibe una respuesta satisfactoria. La política está definida de la siguiente forma:

Parámetro	Valor
Intentos totales	3
Intervalo entre reintentos	0,5 segundos (fijo)
Timeout de conexión HTTP	5 segundos
Timeout de respuesta HTTP	5 segundos

Reprocesamiento batch

Si tras los 3 intentos la entrega sigue fallando, los eventos no entregados se reintentan mediante un proceso batch interno aproximadamente cada 1 minuto. Este mecanismo asegura alta disponibilidad de entrega incluso ante fallos temporales del endpoint receptor.

Orden de los eventos y entrega desordenada

Zertiban no garantiza que los eventos lleguen en el orden en el que ocurrieron. Los reintentos y el reprocesamiento batch desplazan una entrega fallida hacia el futuro, por lo que un evento reintentado puede llegar por detrás de un evento emitido más tarde: un cambio de estado reintentado a través del proceso batch puede alcanzarte un minuto después del cambio de estado que le siguió.

El timestamp del body es lo que te indica el orden real: registra cuándo ocurrió la acción subyacente y es idéntico en todos los reintentos del mismo evento. Ni la cabecera zb-timestamp ni el orden de llegada sirven para esto, porque ambos reflejan el momento de la entrega. Consulta Los dos timestamps para la comparativa completa.

Estrategia recomendada

La comparación decide si aplicar el estado, no si conservar el evento. Persiste todos los eventos que recibas: una llegada tardía sigue siendo un hecho sobre tu recurso, y varios tipos de evento comparten el mismo resource.uuid sin traer una transición de estado — OPERATION_OPENED y OPERATION_COMPLETED hablan de la misma operación, y descartar el primero porque el segundo llegó antes pierde la apertura, que nunca competía con él.

1. Deduplica primero por eventUuid. Si ya lo has visto, estás ante un reintento: para aquí.
2. Persiste el evento, diga lo que diga su timestamp.
3. Guarda, por uuid de recurso, el timestamp del evento más reciente cuyo estado hayas aplicado.
4. Si el timestamp entrante es posterior, aplica el estado y actualiza el valor almacenado.
5. Si es anterior, el estado que trae está obsoleto: deja tu estado intacto, no vuelvas atrás.
6. Si ambos son iguales, son dos eventos distintos del mismo recurso en el mismo instante — eventUuid ya ha descartado que sea un duplicado. Ninguno está obsoleto, así que procesa los dos; si sus estados entran en conflicto, resuélvelo con un criterio propio, porque el payload no los ordena.

Responde 2xx en todos los casos. Un evento cuyo estado hayas omitido se ha recibido correctamente igualmente, y cualquier otra respuesta hará que Zertiban lo reintente.

Deduplicación y orden son dos protecciones distintas

eventUuid evita que el mismo evento se aplique dos veces, timestamp evita que un evento anterior sobrescriba un estado más nuevo. Un consumidor necesita las dos: timestamp no es una clave de idempotencia, porque dos eventos distintos del mismo recurso pueden compartirlo.

Solución de problemas: no recibo notificaciones

Si los webhooks no están llegando correctamente, verifica los siguientes puntos:

1. Registro del endpoint. Confirma con Zertiban que la URL está correctamente registrada, está activa y está asociada al businessUuid correcto.
2. Accesibilidad externa. El endpoint debe ser accesible públicamente vía HTTPS. Para pruebas externas puedes usar herramientas como reqbin.com o cualquier cliente HTTP fuera de tu red interna.
3. Respuesta del endpoint. El endpoint debe responder únicamente códigos 2xx, en menos de 5 segundos. Respuestas 3xx, 4xx o 5xx pueden provocar reintentos o pérdida de eventos.
4. Desarrollo local. Para entornos locales expón el endpoint mediante túneles HTTPS, por ejemplo con ngrok (ngrok http 3000). La URL pública generada puede utilizarse como endpoint temporal en sandbox.
5. Validación de firma. Durante la fase inicial de integración, acepta todos los webhooks sin bloquear, registra zb-signature y zb-timestamp, y valida posteriormente el cálculo de firma. Esto facilita detectar discrepancias en la implementación del algoritmo.

Atajo de debug

Loguea siempre eventUuid, eventType, zb-timestamp y el resultado de la verificación de firma. Este enfoque simplifica el diagnóstico de incidencias y reduce significativamente el tiempo de integración.

Recomendación final

El diseño correcto de un consumidor de webhooks debe priorizar:

• Idempotencia.
• Baja latencia en la respuesta.
• Procesamiento asíncrono.
• Tolerancia a reintentos.

Esto garantiza una integración robusta, escalable y consistente con el modelo de entrega de Zertiban.