Idempotency Key

An idempotency key is a unique string you send with a Stripe POST request so that retrying it never performs the action twice. If a network error leaves you unsure whether a charge went through, you can safely resend the same request with the same key — Stripe recognizes it and returns the original result instead of creating a duplicate.

How it works

You generate a unique value (a UUID is common) and pass it in the Idempotency-Key header. Stripe records the outcome of the first request under that key. On any retry with the same key:

• If the first request completed, Stripe returns the cached response — same status, same object — without doing the work again.
• If it failed with a 400, the same 400 comes back, because error responses are cached too.

Keys expire from Stripe's system after 24 hours, so a retry must happen within that window to be recognized. One caveat: a request rejected by the rate limiter with a 429 runs before the idempotency layer, so it can still produce a different result on retry.

Why it matters

Networks are unreliable, and the worst failure mode in payments is charging a customer twice. Idempotency keys make writes safe to retry, which is why Stripe recommends attaching one to every POST — creating a PaymentIntent, issuing a refund, or any mutating call.

Idempotency beyond the key

The same principle applies to consuming events: because webhooks can be delivered more than once, handlers should dedupe on the event id so a repeated delivery isn't processed twice. ChargeBell dedupes on the Stripe event id for exactly this reason, so one payment never produces two Slack alerts.