Cómo reintentar eventos webhook sin duplicar acciones en un SaaS

Usa referencias, estados y claves de idempotencia para reanudar entregas repetidas sin crear pagos, tickets o registros duplicados.

Equipo enginerIT· 3 min de lectura

Repetir un evento no debe repetir el efecto

Un webhook puede llegar más de una vez si la respuesta se pierde o el emisor repite una entrega que no confirmó. Si el receptor crea una acción por cada petición, podrían duplicarse tickets, mensajes o actualizaciones. El sistema necesita distinguir evento recibido, procesado y aplicado, y decidir si un reintento es seguro usando la referencia y el estado final.

Separa evento de efecto de negocio

Registra el identificador que proporciona el emisor y la acción que tu servicio realiza al procesarlo. Dos llamadas HTTP pueden representar el mismo hecho; dos eventos distintos pueden producir valores similares. No deduzcas duplicado solo por el contenido del JSON.

Guarda estados por evento y cuenta

Modela recibido, validado, en proceso, completado, rechazado y respuesta pendiente según tu sistema. Relaciona estado con tenant y origen. Una clave global sin contexto puede colisionar entre cuentas, por lo que la regla de unicidad debe reflejar el alcance real.

Comprueba si el primer intento ejecutó la acción

Si hay timeout, puede que el destino guardara el cambio y que el emisor no recibiera confirmación. Consulta estado final mediante la referencia de negocio antes de crear otro efecto. Si no se puede consultar, guarda incertidumbre y deriva el caso a reconciliación.

Aplica una clave idempotente en el punto de efecto

La protección debe envolver la creación o actualización que no puede repetirse, no solo la recepción de la petición. Define qué hace una solicitud con la misma clave y contenido cambiado. Si el emisor genera otra referencia en cada reintento, usa contrato o mapeo autorizado, no una heurística oculta.

Valida esquema y versión antes de transformar

Comprueba campos requeridos, tipo de evento y versión de payload. Conserva el cuerpo original en un almacenamiento autorizado y elimina secretos de logs. Si llega un formato nuevo, no conviertas valores desconocidos en ceros o cadenas vacías para dejar pasar el evento.

Configura reintentos con límites y cola de errores

Define frecuencia, máximo y condición de salida por clase de fallo. Un error permanente de validación no mejora al repetirse cada minuto. Asigna eventos agotados a una cola revisable con referencia, síntoma y acción, sin perder el orden si el proceso depende de eventos previos.

Prueba duplicados, reordenación y concurrencia

Simula la misma entrega dos veces, eventos en orden inverso, dos workers en paralelo y una escritura que tarda más que el timeout. Verifica que el efecto ocurre una sola vez y que una segunda ejecución devuelve un resultado entendible. Incluye eventos válidos con contenido semejante para evitar bloquearlos como duplicados.

Mide entrega, procesamiento y efectos

Separa tasa de reintentos de acciones duplicadas y eventos sin respuesta. Guarda indicadores por emisor, versión y tenant. Una subida de reintentos puede ser un problema de red; una acción repetida indica que la protección está en otra etapa o tiene una clave incorrecta.

Antes de ponerlo en marcha

✓ Identificador único del evento
✓ Origen y cuenta verificados
✓ Intentos y respuestas consultados
✓ Efecto final comprobado
✓ Regla idempotente documentada
✓ Reintento limitado y monitorizado

Ejecuta la misma referencia dos veces con una respuesta perdida tras la primera escritura.

Comprueba que el segundo procesamiento detecta el efecto existente y que un evento distinto con el mismo contenido sí puede continuar.

Cuéntanos qué necesitas →