Idempotent Payment Webhook with Postgres & HTTP API

Stop duplicate payments with an idempotent payment webhook for n8n

This n8n workflow exposes a payment webhook that uses Postgres as an idempotency store, ensuring your external payment provider API is called only once per Idempotency-Key—and replaying the stored result on retries.

What this workflow does

• Receives webhook requests via a POST endpoint with an Idempotency-Key header and a JSON payment payload.
• Creates/ensures Postgres storage (the required idempotency_keys table and indexes) so request status and stored responses are tracked safely.
• Validates and scopes the key by client ID, then computes a SHA-256 fingerprint of a canonicalized payload to detect mismatches.
• Atomically claims the idempotency key in Postgres:
  • If new: it proceeds to call the payment provider.
  • If completed: it replays the stored response to the caller.
  • If the same key is reused with a different payload: it rejects as a duplicate-order mismatch.
  • If the request is still running: it returns an in-progress / duplicate-order error.
• Calls the configured provider endpoint once using an HTTP Request, forwarding the same Idempotency-Key header.
• Stores outcome back to Postgres, classifying provider responses as replayable success/decline or failed (retryable timeout/5xx/429), and responds with Idempotency-Key and Idempotent-Replayed headers.

Use cases

• Prevent accidental double-charges when clients retry payment webhooks after timeouts.
• Guarantee consistent payment results for SaaS billing flows under network instability.
• Handle high-volume inbound payment events safely by deduplicating via Idempotency-Key + payload fingerprinting.

Technical details

• Nodes/stack: Webhook, if, Code, Postgres, Sticky Note, HTTP Request
• Core mechanisms: Postgres-backed idempotency, SHA-256 payload fingerprinting, atomic claim/replay logic
• Config: set providerUrl and policy values such as leaseSeconds and providerTimeoutMs (as provided in the workflow setup)