Run It Twice, Charge Once: Idempotency Keys in n8n

Описание и применение

Внедрение ключей идемпотентности в рабочие процессы n8n предотвращает дублирование операций, таких как двойные списания и сообщения, при повторных попытках выполнения.

Задача

A workflow retried after a timeout, causing duplicate side effects such as double charging, double messaging, and duplicate record updates, while logs only showed success.

Результат

Implementing idempotency keys in n8n workflows eliminates duplicate side effects caused by retries, ensuring that each operation is performed only once even if the workflow is retried or replayed.

Рабочий процесс

• Generate a stable idempotency key from job ID and operation name (e.g., "job-4821:charge").
• Before performing a side effect, query a durable shared store for the key.
• If a result exists, return it and skip the side effect.
• If no result, perform the side effect, then atomically write the result to the store under the key in the same step.
• Ensure the store is durable, shared, and visible to all retry paths (ordinary retry, DLQ replay, checkpoint resume).
• Apply a retention policy for keys that covers the longest retry/replay window.
• When a retry returns a stored result, record the outcome as a duplicate skip in the job record for visibility.

Доказательства

The customer was charged twice, messaged twice, and every log said "success," because each execution had, in isolation, succeeded.

Источник

The fix is one extra field, carried through the whole workflow: an idempotency key.

Источник

If a completed result exists for the key, return that result and skip the side effect entirely.

Источник

The store does not need to be fancy. A table with the key, the operation, the result, and a timestamp is enough.

Источник