¿Cómo se maneja la reclamación atómica para duplicados de webhook?

Para receptores de webhook en producción, ¿cómo estás manejando el reclamo atómico?

Una búsqueda seguida de una escritura deja un hueco donde dos ejecuciones pueden ver ambas ‘no visto’ antes de que cualquiera guarde ‘visto’. En un laboratorio secuencial usé una clave de evento con alcance, pero no he probado la seguridad concurrente allí.

¿Usas una restricción única de base de datos, Data Tables u otro almacén para el reclamo — y cómo manejas la ruta de conflicto?

@operantsolo

Para evitar condiciones de carrera en entornos de alta concurrencia, debes alejarte de la lógica «verificar-luego-actuar» (búsqueda seguida de escritura) y en su lugar utilizar una estrategia de inserción atómica. El método más robusto es usar una base de datos como PostgreSQL con una restricción UNIQUE en tu identificador de evento. Al intentar hacer INSERT del ID del evento como el primer paso después de recibir el webhook, permites que la base de datos maneje la sincronización; si la inserción falla debido a una violación de unicidad, la ejecución ha encontrado un duplicado y puede terminarse o redirigirse de forma segura.

Para flujos de trabajo complejos o de larga duración, puedes extender esto a un patrón dirigido por estado para manejar fallos parciales. En lugar de una simple verificación de existencia, insertas un registro con un estado como processing y lo actualizas a completed solo después de que el flujo de trabajo tenga éxito. Este enfoque «basado en intenciones» garantiza que si un flujo de trabajo se bloquea a mitad de camino, puedas distinguir entre un evento que se está manejando actualmente, uno que falló y necesita un reintento, y uno que ya ha sido completamente procesado.

Aunque n8n proporciona un nodo Remove Duplicates integrado para deduplicación ligera, generalmente no se recomienda para webhooks de producción críticos para la misión porque se basa en el historial de ejecución interno de n8n y puede no proporcionar la atomicidad estricta y distribuida requerida para escenarios de alta concurrencia. Para máxima confiabilidad, usar una base de datos externa como tu «fuente de verdad» para idempotencia mediante restricciones únicas sigue siendo el estándar de la industria.

Para añadir el lado de n8n y la ruta de conflicto al enfoque de restricción única anterior:

Reclamación. Conviértelo en una sentencia en un nodo Postgres (Execute Query), justo después del nodo Webhook:

INSERT INTO webhook_claims (event_key)
VALUES ($1)
ON CONFLICT (event_key) DO NOTHING
RETURNING event_key;

event_key es la clave principal o tiene una restricción única. Pasa la clave a través de Query Parameters, no construyendo la cadena SQL. Con ON CONFLICT, un duplicado no es un error, así que no necesitas ramas de error para el caso normal.

Ruta de conflicto. La primera ejecución obtiene una fila; un duplicado no obtiene ninguna. Lo que el nodo genera para «sin filas» puede diferir según la versión del nodo, así que prueba el valor en lugar de contar elementos: activa Always Output Data en el nodo, luego añade un nodo IF verificando que {{ $json.event_key }} existe.

  • Verdadero: realiza el trabajo.
  • Falso: detente y sigue respondiendo al remitente con un 2xx para que no siga reintentando.

Bloqueos. Una reclamación simple bloqueará un reintento si la ejecución muere después de reclamar. Si necesitas reintentos, añade columnas status y claimed_at y permite que una reclamación antigua o fallida se tome de nuevo:

INSERT INTO webhook_claims (event_key, status, claimed_at)
VALUES ($1, 'processing', now())
ON CONFLICT (event_key) DO UPDATE
  SET status = 'processing', claimed_at = now()
  WHERE webhook_claims.status = 'failed'
     OR (webhook_claims.status = 'processing'
         AND webhook_claims.claimed_at < now() - interval '15 minutes')
RETURNING event_key;

Establece el intervalo más largo que tu ejecución más lenta, y escribe status = 'done' como paso final.

Tablas de datos. No las he probado bajo escrituras concurrentes, así que no las usaría para esto hasta que hayas ejecutado la prueba siguiente.

Para verificar: envía 20 solicitudes paralelas con la misma clave (por ejemplo curl en un bucle con &). Deberías ver una fila en la tabla y una ejecución en la rama Verdadero; las otras 19 van a Falso.

Minimolo

Agregando al enfoque de restricción única: ayuda almacenar un estado con la fila de reclamación (por ejemplo, procesando y finalizado) más una marca de tiempo, no solo el ID del evento. Una simple bandera de “visto” tiene una brecha cuando una ejecución reclama un evento y luego falla antes de terminar, porque el reintento se tratará como duplicado y el evento se pierde.

Con un estado y marca de tiempo, puedes permitir que un reintento asuma una reclamación que ha estado procesándose demasiado tiempo, mientras aún rechazas eventos que están en progreso o ya finalizados.

Además, usar INSERT … ON CONFLICT DO NOTHING y verificar el recuento de filas afectadas te da el resultado de la reclamación en una única instrucción atómica, por lo que la ruta de conflicto es simplemente una rama IF en ese recuento. Y responde al remitente rápidamente (por ejemplo, con el nodo Responder a Webhook) para que no reintente mientras tu flujo de trabajo aún se está ejecutando.

Una restricción UNIQUE de PostgreSQL es un buen punto de partida para la afirmación atómica.

Un caso extremo que probaría es cuando una escritura en el CRM descendente tiene éxito, pero el flujo de trabajo se bloquea antes de poder marcar el evento como completado. Al reintentar, el evento sigue en “procesamiento”, aunque el cambio en el CRM ya ocurrió.

Para integraciones de CRM, preferiría un upsert usando un ID externo único donde la API lo admita, o reconciliar el registro de destino antes de reintentar mientras se protege contra reintentos concurrentes.

Una concesión o tiempo de espera puede ayudar a recuperar afirmaciones abandonadas, pero no hará que las llamadas a API descendentes sean idempotentes por sí solas.

¿Principalmente intentas evitar escrituras duplicadas, o también necesitas recuperar ejecuciones parcialmente completadas?

Utiliza una restricción única de base de datos en el ID del evento e inserta primero, en lugar de buscar y luego escribir. Si la inserción tiene éxito, posees el evento, y si falla con un conflicto, detente y devuelve 200 para que el remitente no reintente. Postgres con ON CONFLICT DO NOTHING funciona bien, y verificar si se devolvió una fila te indica por qué camino vas.

Una brecha en la ruta «Eliminar elementos procesados en ejecuciones anteriores» es el tamaño del historial. Con «El valor es nuevo», el tamaño del historial establece cuántos elementos almacena el nodo, y por defecto es 10.000. Si el almacén mantiene solo los ID más nuevos, un reintento tardío de un evento más antiguo se verá nuevo y pasará. Por lo tanto, ajusta el tamaño del historial a tu ventana de reintento más larga, no solo a tu volumen diario.

La documentación no describe el comportamiento en ejecuciones simultáneas, así que no confiaría en este nodo para la reclamación atómica. Una inserción con una restricción única en Postgres es el patrón más seguro para esa parte. ¿Tu ventana de reintento es más larga que la cantidad de eventos que almacenas?