Imagine an agent submitting an order. The server creates it, but the response never reaches the agent. A retry with a new operation identifier can create a second order. An idempotency key gives a supporting API a way to recognize another attempt at the same logical operation.
Keep that key stable across retries of the same operation. A genuinely new order needs a new key. The API’s rules still matter: Stripe documents parameter checks and, for API v1, possible key removal after at least 24 hours. Reusing a key after removal can start a new request.
Idempotency describes an operation’s effect; it does not guarantee that a message is delivered exactly once. Webhooks can arrive more than once. Their receivers need duplicate handling, while signature verification answers the separate question of whether the message is authentic.
Sources
- Stripe API: Idempotent requests — Explains retrying with a client-generated key, parameter checks and the API v1 key-retention boundary; checked October 26, 2026.
- Stripe Docs: Receive Stripe events in your webhook endpoint — Documents duplicate-event handling and signature verification for webhook receivers; checked October 26, 2026.