Webhooks e idempotencia: cómo evitar pedidos duplicados en una integración
Por Carlos Isidoro De Ayala Diaz ·
Webhooks e idempotencia en ERP y CRM: cómo evitar pedidos duplicados, eventos perdidos y reintentos inseguros en integraciones empresariales críticas.
Diseña el contrato del evento antes de elegir la cola
Una integración entre ERP, CRM, comercio electrónico o aplicación móvil no termina cuando dos sistemas intercambian JSON. El reto aparece cuando una respuesta se pierde, un proveedor repite una notificación o un proceso queda a medias. Antes de decidir si se usará un webhook, una cola o una consulta programada, la empresa debe definir qué hecho de negocio se comunica, qué sistema lo origina y qué resultado se espera. Un pedido confirmado, un cliente actualizado y una factura emitida necesitan reglas diferentes.
El contrato del evento identifica como mínimo un ID estable, tipo, versión, fecha de ocurrencia, productor y entidad afectada. El identificador de entrega no debe confundirse con la clave de negocio: una misma venta puede generar varios eventos legítimos, mientras una misma entrega puede repetirse. La versión permite evolucionar campos sin romper receptores antiguos. Cada consumidor documenta qué versiones acepta, qué datos son obligatorios y qué hace cuando recibe un valor desconocido.
Conviene enviar solo la información necesaria. En muchos casos el webhook funciona mejor como aviso y el receptor consulta después el recurso actual mediante una API autenticada. Esto reduce datos sensibles en tránsito y evita actuar sobre una fotografía obsoleta, aunque añade dependencia del sistema origen. Si el evento incluye el estado completo, se define su vigencia, la clasificación de cada campo y el tratamiento de cambios posteriores. Las URL no deben contener secretos, credenciales ni datos personales.
El contrato también expresa qué significa éxito. Un código 2xx puede confirmar que el receptor validó y almacenó el evento de forma duradera, sin afirmar que el ERP ya terminó todo el proceso. Separar aceptación y resultado evita mantener abierta una petición mientras se actualizan varios sistemas. La documentación registra límites de tamaño, tiempo máximo, autenticación, orden esperado, ventana de reintento y propietario de cada extremo. Así la arquitectura responde a un acuerdo verificable y no a supuestos entre proveedores.
Asume reintentos, duplicados y entregas fuera de orden
En una red distribuida, un timeout no demuestra que la operación fallara. El servidor puede haber creado el pedido y perderse únicamente la respuesta. Si el emisor repite sin una regla de idempotencia, el segundo intento puede crear otro pedido, cargo o aviso. RFC 9110 define una operación idempotente como aquella cuyo efecto previsto es el mismo tras una o varias peticiones idénticas. Un POST no adquiere esa propiedad por añadirle un nombre; la aplicación debe implementarla con un identificador y una decisión persistente.
La clave idempotente representa una intención de negocio concreta y se conserva junto al resultado. El receptor reserva la clave y ejecuta el cambio de forma atómica, o coordina ambos pasos para que dos procesos simultáneos no ganen la misma carrera. Si llega un reintento con la misma clave y los mismos parámetros, devuelve el resultado conocido o el estado del proceso. Si la clave se reutiliza con datos incompatibles, rechaza la petición y genera una alerta, porque podría ocultar un error del cliente.
El periodo de conservación de las claves debe cubrir la ventana real de reintentos y la recuperación manual. Eliminar una clave demasiado pronto convierte un intento tardío en una operación nueva. Conservarla indefinidamente puede añadir volumen y conflictos si el emisor recicla identificadores. AWS y Stripe documentan el patrón de token generado por el cliente para reconocer solicitudes repetidas; el plazo y la respuesta exacta forman parte del contrato y deben probarse en la implementación elegida.
La deduplicación no resuelve el orden. Un evento de envío puede llegar antes que la actualización del pedido, o dos cambios del cliente pueden cruzarse. Para procesos que exigen secuencia se usa una versión monotónica, un número por entidad o una consulta al estado vigente. El receptor ignora versiones antiguas solo cuando la regla de negocio lo permite. Tampoco se promete “exactamente una vez” de extremo a extremo porque una plataforma lo ofrezca en una región o tipo de suscripción: la base de datos y los sistemas posteriores siguen necesitando controles propios.
Separa recepción, procesamiento y recuperación
El punto de entrada verifica autenticidad antes de aceptar trabajo. Cuando el proveedor firma el webhook, la firma se calcula sobre el cuerpo original, no sobre un objeto JSON ya transformado. También se valida la marca de tiempo dentro de una ventana para limitar repeticiones y se identifica el secreto correspondiente al entorno. La rotación puede requerir aceptar dos claves durante un periodo controlado. Filtrar por direcciones IP puede complementar el control, pero no sustituye la firma ni la autorización del evento.
Después de validar formato, origen e identificador, el receptor almacena el evento o lo entrega a una cola y responde con rapidez. Un trabajador procesa de forma asíncrona los efectos sobre ERP, CRM o proveedores. Esta separación absorbe picos y evita que la latencia de un sistema externo provoque reintentos innecesarios. La aceptación solo se confirma cuando el mensaje quedó durable; devolver éxito antes de guardar puede perderlo, y devolver error después de guardarlo puede causar una repetición que la idempotencia debe tolerar.
Los reintentos se limitan y clasifican. Un timeout, un 429 o una indisponibilidad temporal pueden justificar espera exponencial con variación aleatoria; un dato inválido o un permiso denegado requieren corrección, no cien intentos idénticos. Google Cloud documenta las colas de mensajes no procesables para apartarlos tras un número configurado de entregas. Esa cola no es un cementerio: conserva causa, contexto depurado, propietario y una operación segura para reanudar o descartar.
Un flujo con varios efectos necesita reconciliación. Si el pedido se creó en el ERP pero falló la notificación al CRM, repetir todo puede duplicar la primera parte. El proceso registra cada paso con una clave correlacionada y decide si continúa, compensa o solicita intervención. Las operaciones externas reciben sus propias claves idempotentes cuando las admiten. Cuando no las admiten, se consulta el estado antes de repetir o se aplica una restricción local. Ningún reintento automático debe convertir una incertidumbre técnica en un nuevo hecho comercial.
Prueba los fallos y opera la integración con evidencias
Las pruebas útiles provocan los fallos que rara vez aparecen en una demostración. Se corta la conexión después de aplicar un cambio y antes de recibir la respuesta; se envía el mismo evento en paralelo; se altera el orden; se agota el tiempo de una dependencia y se introduce un mensaje incompatible. Para cada caso se comprueba el estado final en todos los sistemas, la respuesta al emisor, el registro de la clave y la posibilidad de recuperar el proceso. Una prueba feliz no demuestra tolerancia a reintentos.
La observabilidad debe responder qué pasó con un pedido sin registrar contraseñas ni cuerpos completos. Conviene conservar ID de evento, clave idempotente, entidad, versión, origen, receptor, intento, estado, duración y correlación con cada sistema. Las métricas incluyen antigüedad del mensaje más viejo, profundidad de cola, tasa de reintentos, duplicados detectados y elementos apartados. Una alerta necesita umbral y responsable; contar errores sin revisar acumulación o retraso puede dejar una integración aparentemente disponible mientras pierde actualidad.
La conciliación periódica compara hechos de negocio, no solo respuestas HTTP. Se revisan pedidos, importes, estados o clientes entre origen y destino para localizar ausencias y divergencias que escaparon al flujo en tiempo real. El procedimiento describe cómo reconstruir un intervalo, qué fuente prevalece y quién autoriza una corrección. También existe un runbook para pausar consumidores, rotar secretos, reprocesar mensajes y comunicar impacto. La recuperación manual se ensaya antes de necesitarla con datos de producción.
Élite Solutions Tech puede definir desde Murcia una integración para empresas regionales y proyectos nacionales, detallando contratos, autenticación, idempotencia, colas, pruebas, observabilidad y mantenimiento. La propuesta identifica qué sistemas y proveedores participan, qué parte controla cada uno y qué queda fuera. No promete ausencia absoluta de duplicados ni continuidad sin límites: entrega mecanismos verificables para detectar, contener y recuperar fallos. Para valorar un caso concreto puedes indicar en contacto qué sistemas intercambian datos y qué operación no debería repetirse.