Run It Twice, Charge Once: Idempotency Keys in n8n

Description and use

Implementing idempotency keys in n8n workflows prevents duplicate operations like double charges and messages during retries.

Problem

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.

Outcome

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.

Workflow

• 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.

Evidence

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

Source

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

Source

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

Source

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

Source