Idempotencia en webhooks: evitar efectos duplicados

Por qué una misma entrada puede llegar otra vez

Un sistema que recibe eventos debe contemplar entregas repetidas, demoras y fallos parciales. La política exacta de reintentos depende del proveedor y del evento; no conviene asumir un plazo universal ni que cada petición representa una acción nueva.

La idempotencia busca que repetir la misma operación no produzca efectos adicionales indebidos. Es especialmente relevante cuando una entrada puede crear una cita, un contacto o una orden. Esta guía propone controles de diseño, sin atribuir incidentes a clientes ni prometer que un sistema existente ya los cumple.

Define una clave con alcance suficiente

Una clave útil combina el identificador estable del evento con su contexto: proveedor, cuenta y canal o bandeja, según el contrato. No se debe deduplicar únicamente por texto: dos personas pueden enviar el mismo mensaje y una persona puede repetirlo legítimamente.

El identificador del navegador tampoco prueba por sí solo la identidad de un contacto. La cuenta y la conversación deben validarse con el sistema autorizado antes de asociar información.

Registra antes de reconocer la recepción

Un patrón consiste en validar lo mínimo, guardar la entrada en una bandeja durable y después reconocerla según el contrato del proveedor. Un trabajador procesa los registros pendientes. Si la base de datos no confirmó la escritura, devolver una aceptación puede perder trabajo.

La restricción única y una operación atómica evitan que dos procesos inserten simultáneamente el mismo evento. PostgreSQL documenta ON CONFLICT para resolver conflictos con restricciones únicas. Eso protege esa escritura concreta; no convierte automáticamente todas las acciones externas en idempotentes.

La acción externa también necesita protección

Si el proveedor acepta claves de idempotencia, se utiliza una clave estable para la operación lógica. Si no las acepta, se guarda la referencia externa y se consulta el resultado antes de repetir una creación incierta. Un timeout no demuestra que la operación falló.

Una tarea en memoria puede desaparecer al reiniciar el servidor. Para trabajo que debe recuperarse, se requiere almacenamiento durable, estados y una política de reintentos acotada. Un flujo de errores como el de n8n necesita esa definición de negocio además del manejo técnico.

Duplicados y pruebas mínimas

Datos de prueba. Dos trabajadores reciben el mismo evento de una bandeja compartida. Ambos intentan registrarlo; sólo uno obtiene el derecho a procesarlo. El otro reconoce que ya existe. Si la creación externa queda incierta, se consulta su referencia y se mantiene pendiente hasta reconciliarla.

Prueba simultaneidad, reinicio después de guardar, caída después de crear afuera, evento repetido y dos eventos distintos con el mismo texto. Comprueba el número de efectos finales, no únicamente el número de respuestas HTTP exitosas.

Antes de conectar un canal real

Define retención, acceso a registros, eliminación de datos y responsable de excepciones. Evita guardar tokens, mensajes completos o datos personales en telemetría técnica sin una necesidad definida. La implementación de agentes debe acordar estos controles y sus pruebas; puedes plantear tu integración sin compartir credenciales.