Política de reenvío
Cuando una entrega de webhook falla, la reprocesamos automáticamente con espera exponencial para maximizar la confiabilidad de la entrega.
¿Qué cuenta como fallo?
Una entrega se considera fallida cuando tu endpoint responde con cualquier código distinto de 200, 201, 202 o 204, o cuando la conexión expira (tiempo límite de 30 s por intento, configurable por webhook).
Calendario de reintentos
Las entregas fallidas se reintentan hasta 5 veces en total por defecto (configurable por webhook), con espera exponencial: la espera se duplica aproximadamente antes de cada nuevo intento, empezando en ~2 s. Con la configuración por defecto, los 5 intentos ocurren en unos 30 segundos desde el primero; a cada espera se le suma una pequeña variación aleatoria (jitter) para evitar que los intentos lleguen todos en el mismo instante.
| Intento | Espera antes de este intento |
|---|---|
| #1 | 0s |
| #2 | ~2s |
| #3 | ~4s |
| #4 | ~8s |
| #5 | ~16s |
El intento n.º 1 es el envío original, hecho de inmediato. Las esperas mostradas son aproximadas: los valores reales varían un poco por el jitter.
Fallo permanente: Cuando se agota el número de intentos configurado (5 por defecto), esa entrega se marca como fallida de forma permanente. Puedes revisar las entregas fallidas en el historial del webhook, en el CRM.
Pausa automática del webhook: Esto es distinto de los reintentos de una sola entrega: si un webhook acumula 10 intentos de entrega consecutivos con fallo (contados por intento, incluidos los reintentos del mismo evento, no solo eventos distintos), se pausa automáticamente y deja de recibir nuevos eventos hasta que se reactive manualmente en el CRM.
Idempotencia
Como los reintentos pueden entregar el mismo evento más de una vez, tu endpoint debe ser idempotente. Usa el header X-Webhook-Event-Id para eliminar duplicados: se mantiene igual en todos los intentos de entrega de un mismo evento, a diferencia de X-Webhook-Delivery-Attempt, que aumenta en cada reintento.
const processedDeliveries = new Set(); // Use Redis in production
app.post('/webhook', (req, res) => {
const eventId = req.headers['x-webhook-event-id'];
if (processedDeliveries.has(eventId)) {
// Already processed — acknowledge and skip
return res.sendStatus(200);
}
// Process the event
handleEvent(req.body);
processedDeliveries.add(eventId);
res.sendStatus(200);
});Buenas prácticas
- Responde con 200 OK lo antes posible. Encola el procesamiento pesado de forma asíncrona (SQS, BullMQ, etc.).
- Nunca devuelvas 5xx por errores de lógica de negocio: responde 200 y regístralo localmente. Solo 200, 201, 202 y 204 cuentan como éxito; cualquier otro código (sobre todo 5xx) dispara un reintento.
- Valida siempre la firma HMAC antes de procesar (consulta la página de Seguridad).
- Guarda el ID del evento (X-Webhook-Event-Id) en una base de datos para tratar con seguridad los eventos duplicados.
- Vigila los tiempos de respuesta de tu endpoint: mantenlos por debajo de 5 s para evitar que expiren.