Idempotency Key

An idempotency key is a unique string you send with a Stripe POST request. If you retry the request with the same key, Stripe returns the result of the first attempt instead of doing the work again. If a network error leaves you unsure whether a charge went through, you can resend it without charging the customer twice.

How it works

Generate a unique value, such as a V4 UUID, and send it in the Idempotency-Key header. Stripe saves the status code and body of the first request under that key, whether it succeeded or failed. A retry with the same key gets the same response, including a 500 error.

Some details:

• Stripe saves a result only once the endpoint starts running. If the request fails validation or conflicts with another request running at the same time, nothing is saved and you can retry.
• Stripe compares the retry's parameters with the original and returns an error if they differ.
• Stripe may remove keys once they are 24 hours old. A retry after that runs as a new request.
• Keys can be up to 255 characters. Don't use emails or other personal data as keys.

Why it matters

Charging a customer twice is one of the worst payment bugs. Idempotency keys make every create or update safe to retry, such as creating a PaymentIntent or issuing a refund. GET and DELETE requests don't need keys.

The same idea for webhooks

Stripe can deliver the same webhook event more than once, so handlers should skip events they have already processed. ChargeBell stores each Stripe event ID once, so a repeated delivery doesn't post a second Slack alert.