Crea un webhook idempotente en n8n que omita las solicitudes reintentadas
Guarda claves de idempotencia en una data table de n8n, omite reintentos consecutivos, prueba en Executions y conoce el límite de concurrencia.
Comprobado con la documentación de n8n el .
Qué significa la idempotencia en un webhook y qué necesitas
Una definición sencilla, con nuestras propias palabras: un webhook es idempotente cuando recibir la misma solicitud por segunda vez no crea un segundo registro ni repite un efecto secundario. Esto importa porque muchos emisores reintentan cuando no reciben una respuesta limpia. Cómo y cuándo reintentan depende del emisor, y la documentación de n8n usada para este tutorial no lo cubre.
Antes de empezar necesitas tres cosas. Primero, tu propia instancia de n8n. Segundo, un workflow que empiece con un trigger Webhook. Tercero, acceso a data tables. También necesitas un emisor que incluya su propia clave de idempotencia en cada solicitud, por ejemplo en una cabecera o en un campo del cuerpo. Te sugerimos no generar la clave dentro de n8n. Una clave creada en cada ejecución es distinta cada vez, así que no puede indicarte que dos solicitudes son en realidad la misma.
El objetivo es un registro por clave de idempotencia, incluso cuando el emisor reintenta. Las claves nuevas ejecutan el efecto secundario, como crear un pedido o enviar un correo. Las claves repetidas reciben una respuesta clara y no ocurre nada más. Esta guía se basa en la documentación oficial. No la hemos probado de primera mano.
Pasos 1 y 2: protege el webhook y crea la tabla de claves
Añade un nodo Webhook. En la autenticación, exige que quienes lo llamen usen Basic, Header o JWT auth. Nuestro razonamiento es simple: limita quién puede llamar al webhook. La configuración de las credenciales se explica en otra página de la documentación. Después, configura la opción Respond para usar un nodo Respond to Webhook. Así eliges qué recibe el emisor, incluido un código de respuesta personalizado. Ten en cuenta que el nodo Respond to Webhook se ejecuta solo una vez y usa el primer elemento entrante.
Recuerda también que la URL de producción solo se activa después de publicar el workflow.
Ahora crea una data table para las claves procesadas. Una estructura sencilla tiene una columna para la clave y, si quieres, otra para el momento en que la recibiste. La documentación de n8n menciona expresamente guardar marcadores para evitar ejecuciones duplicadas como un uso de las data tables, así que encaja con su propósito.
Pasos 3 a 5: comprueba, registra, actúa y responde
Paso 3: justo después del webhook, añade un nodo Data Table que separe los elementos entrantes según exista o no una fila coincidente. Compara la clave de la solicitud con la columna de claves. Ahora tienes dos ramas: claves nuevas y claves ya vistas.
Paso 4: en la rama de claves nuevas, inserta la clave con la operación Insert y luego ejecuta tu efecto secundario. Hay una concesión que debes decidir a propósito. Si registras la clave primero, un fallo durante el efecto secundario hace que un reintento se omita, así que el trabajo quizá nunca se haga. Si registras la clave después del efecto secundario, un fallo entre ambos puede permitir que un reintento lo ejecute de nuevo. También existe Upsert, que actualiza una fila ya existente. Sin embargo, la documentación no dice que sea seguro cuando las solicitudes llegan al mismo tiempo.
Paso 5: termina ambas ramas con un nodo Respond to Webhook. Como sugerencia editorial, devuelve también un estado de tipo éxito para los duplicados, con un mensaje que indique que la solicitud ya se procesó. Así los emisores no tienen motivo para seguir reintentando. n8n no exige ningún código de estado concreto. La elección es tuya y de tu emisor.
Paso 6: prueba enviando la misma solicitud dos veces
Publica el workflow y envía una solicitud con una clave inventada, usando el cliente HTTP que prefieras. Después envía exactamente la misma solicitud otra vez. Lo que deberías ver: la primera llamada ejecuta el efecto secundario y añade una fila, y la segunda recibe tu respuesta de duplicado sin añadir filas. Envía una tercera solicitud con otra clave para confirmar que las claves nuevas siguen pasando.
Las ejecuciones de producción no muestran sus datos en el editor, así que abre la pestaña Executions del workflow para ver qué rama siguió cada ejecución. Luego revisa la data table para confirmar que solo hay una fila para la clave repetida.
Sources: S1
Alternativa: el nodo Remove Duplicates
Si no necesitas una tabla que puedas consultar, el nodo Remove Duplicates puede descartar elementos cuyos valores aparecieron en ejecuciones anteriores. Está disponible en n8n 1.64.0 y posteriores. Por defecto almacena 10.000 elementos, y puedes cambiar ese tamaño. Las claves muy antiguas pueden acabar saliendo de ese historial. La documentación no explica qué ocurre con las entradas más antiguas, así que no confíes en él para claves que deban recordarse durante mucho tiempo. Tampoco está documentado su comportamiento cuando las solicitudes llegan al mismo tiempo.
Sources: S5
Solución de problemas y el límite de concurrencia conocido
El emisor recibe un error 500: si el workflow falla antes de que se ejecute un nodo Respond to Webhook, n8n devuelve un 500. Algunos emisores reintentan después, así que un error aquí puede crear justo los reintentos que intentas gestionar. Abre Executions para encontrar el nodo que falló.
Las inserciones fallan de repente: las data tables están pensadas para un almacenamiento ligero o moderado. Por defecto, todas las tablas de una instancia comparten un límite de 200 MiB. Al alcanzarlo, las inserciones fallan y las ejecuciones dan error. Las instancias autoalojadas pueden aumentar el límite con N8N_DATA_TABLES_MAX_SIZE_BYTES.
No pasa nada en producción: comprueba que el workflow esté publicado.
El límite conocido: la documentación usada aquí no garantiza que la comprobación y la inserción ocurran como un único paso atómico, y no menciona restricciones de unicidad. Dos solicitudes idénticas que lleguen en el mismo instante podrían pasar ambas la comprobación y ejecutar ambas el efecto secundario. Esta configuración está pensada para detectar reintentos que llegan uno tras otro, pero no la hemos probado de primera mano y no garantiza protección frente a solicitudes simultáneas. Para pagos u otros efectos secundarios críticos, apóyate en un sistema que imponga una restricción de unicidad a nivel de base de datos.
