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.

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.

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.