workflows

Webhooks duplicados: cómo evitar que un reintento repita la acción

Distingue entrega, evento y efecto de negocio para que un reintento no duplique mensajes, registros o confirmaciones de pago.

Un reintento de entrega no significa una segunda compra. Sin embargo, una automatización que procesa cada notificación como nueva puede volver a enviar un mensaje o actualizar dos veces un pedido. En Argentina, las notificaciones de Mercado Pago ofrecen un ejemplo; en España y otros países hispanohablantes, comprueba primero qué proveedor y modalidad están disponibles. El método no depende de una marca.

Respuesta breve

Evita duplicar el efecto de negocio, no solo la petición HTTP. Valida el origen, deriva una clave estable y conserva o encola la entrega de forma duradera; después confirma pronto la recepción según el contrato del proveedor. El procesamiento asíncrono consulta el estado del objeto y aplica el efecto permitido. Un reenvío encuentra un estado recuperable, no solo una marca de «visto». Otro evento relativo al mismo objeto requiere evaluación.

Stripe documenta entregas duplicadas, reintentos y eventos fuera de orden. n8n explica que el identificador de ejecución cambia en cada activación, por lo que no sirve por sí solo para reconocer un webhook reenviado. Este método no promete efectos «exactamente una vez» en todos los sistemas externos.

Elige la clave según el efecto

Clave posible Identifica Ayuda a evitar Límite
ID de entrega o ejecución Un intento de procesamiento Repetir ese intento Puede cambiar en un reintento
ID del evento Un evento del proveedor Procesar de nuevo el mismo evento Eventos distintos pueden referirse al mismo objeto
ID del objeto + tipo de evento Una transición concreta Repetir esa transición Hay que comprobar el estado y la semántica del proveedor
ID del pedido/pago + acción prevista El efecto de negocio Enviar dos confirmaciones o registrar dos cobros Hay que definir cuándo la acción queda completada

Esta matriz es una síntesis de Pulse. Para confirmar un pago, pregunta «¿se aplicó esta acción a este pago?» y conserva una referencia verificable. Guarda solo los datos personales necesarios para operar y auditar.

Secuencia mínima antes de ejecutar

  1. Verifica firma, remitente y formato según las instrucciones actuales del proveedor. No actúes sobre una notificación no validada.
  2. Extrae el ID del evento y del objeto. Si falta una identidad estable para el efecto, envía el caso a revisión.
  3. Conserva o encola la entrega de forma duradera y confirma pronto la recepción según el protocolo del proveedor. Esa respuesta significa entrega aceptada, no efecto de negocio completado; no esperes una acción externa lenta para responder.
  4. En un proceso separado, reserva la clave de negocio de forma atómica como received/claimed. Consultar y escribir por separado puede fallar con entregas simultáneas. Consulta el estado actual del objeto en el sistema autorizado.
  5. Pasa a processing y ejecuta solo la transición permitida. Usa una clave idempotente en el destino si existe; de lo contrario, conserva un justificante o emplea un patrón inbox/outbox y reconcilia resultados inciertos antes de repetir.
  6. Marca completed solo con evidencia del efecto. Registra failed o uncertain cuando corresponda, con ID y hora. Una reserva abandonada necesita recuperación por cola, lease o plazo; claimed por sí solo nunca prueba la finalización.

Considera ambas direcciones del fallo. Si el proceso cae después de reservar la clave y antes de la acción, la recuperación debe retomar el trabajo pendiente. Si el mensaje salió pero se perdió la respuesta, marca uncertain y revisa el destino antes de repetir. Solo completed indica un efecto confirmado.

Seis casos para verificar antes de activar

Caso hipotético Decisión esperada
Llega dos veces el mismo ID de evento La segunda entrega no repite el efecto
Dos eventos apuntan al mismo pago aprobado La regla comprueba si la acción ya se aplicó
Llega un evento antiguo después del estado actual El flujo no revierte el estado automáticamente
La acción ocurrió, pero falló su confirmación Consultar justificante o destino antes de repetir
Se reservó la clave, pero el proceso cayó antes de la acción Recuperar el estado pendiente y ejecutar la acción una vez
La notificación carece de ID fiable Pausar; no deduplicar por importe y hora aproximados

Son pruebas propuestas, no resultados de Pulse. Antes de activar, demuestra en tu propio entorno controlado que cada caso produce una decisión rastreable.

El plan de contingencia de automatización cubre la recuperación más amplia. Tras un pago, conciliar cobros, ventas y extracto bancario sigue siendo necesario: evitar un webhook duplicado no demuestra que el dinero se haya liquidado.

Fuentes y límites

La documentación de Stripe fundamenta los avisos sobre reintentos y orden. El artículo de n8n distingue ID de ejecución y clave estable. La documentación argentina de Mercado Pago muestra un caso regional de notificaciones; no implica que el mismo producto esté disponible en España. La secuencia y la matriz son modelos editoriales, no una implantación probada ni una garantía universal.

Fuentes