Also known as: idempotent, idempotency key
Definition
Idempotency is the property that running an operation multiple times produces the same result as running it once. For Stripe webhook handlers, idempotency means storing every processed event.id in a unique-constraint table so retries (Stripe retries failed deliveries for up to 3 days in live mode) cannot duplicate purchases or emails.
Stripe delivers each event at least once, sometimes many times during outages or retries. A webhook handler that processes the same event twice will double-credit a purchase, send two delivery emails, and create two rows in a fulfillment table. Idempotency is the architectural defense: dedup by event.id so duplicate deliveries are detected and skipped.
Create a stripe_events table with id TEXT PRIMARY KEY. Before processing, insert the event ID. If the insert succeeds, process the event and return 200. If the insert fails with a unique-constraint violation (Postgres code 23505), this is a duplicate; skip processing and return 200. The insert-before-process order is critical: process-then-insert allows two concurrent retries to both pass the "have we seen this?" check.
They are separate concerns. The Idempotency-Key header is for outbound calls to Stripe (you generate the key, Stripe ensures repeated requests with the same key return the same response). Webhook idempotency is inbound (Stripe sends the event, you dedup by Stripe's event ID). Both belong in a production-ready Stripe integration.