What is idempotency?

Idempotency is the unsexy plumbing that separates a SaaS that quietly handles network blips from one that calls its users in panic at 2am because the same person was charged for a $99 subscription four times. Networks fail. Webhooks get redelivered. Cron jobs retry. Mobile apps drop connections mid-POST. Without idempotency, every one of those failures has the potential to cause a duplicate side effect — another charge, another email, another record, another notification — that the user did not ask for. With idempotency, retries are safe by construction.

For solo SaaS founders the topic is more urgent than it sounds because the modern stack — Stripe, Supabase, Vercel cron, Inngest, Trigger.dev — ships at-least-once delivery semantics on almost every async surface. The systems retry on your behalf, which means your handlers must be idempotent or they will produce duplicates the moment a network packet drops.

Why idempotency matters

The argument is best made through the disasters that happen without it. Each of these is a real failure mode that has burned production SaaS apps:

• Stripe webhooks delivered twice. Stripe explicitly states that webhook events may be delivered more than once. A handler that creates a subscription record on every customer.subscription.created event without checking for duplicates will create two subscription rows, charge the customer once on the second event handler, and produce a billing record that does not match the source of truth.
• Cron job retried after a timeout. Vercel Cron, GitHub Actions, and most schedulers will re-execute a cron job if it times out without responding. A daily-digest job that sends emails to users without an idempotency check will send the digest twice on any day where the function ran long enough to time out.
• Mobile app retry on network drop. A user taps “Buy now,” the request is sent, the network connection drops before the response comes back, the app retries. The server saw the original request, processed it, started returning a response — but the response never arrived. The retry hits a non-idempotent endpoint and the user is charged twice.
• Background job lost connection mid-run. Inngest, Trigger.dev, BullMQ, and similar systems retry a job whose worker died mid-execution. If the job had already created half its database rows before dying, the retry creates the other half plus duplicates of the first half.

The common thread: every one of these scenarios is a sane, reasonable behavior on the part of the calling system. Stripe is not buggy for delivering a webhook twice; it is being correct under the at-least-once delivery contract. The bug is on the receiving end — in code that assumed each invocation was unique.

The HTTP method semantics primer

The HTTP spec has had idempotency baked into method semantics for decades. RFC 9110 defines four of the standard HTTP methods as idempotent by specification:

• GET — idempotent. Multiple GETs to the same URL must return the same resource without side effects.
• PUT — idempotent. Multiple PUTs to the same URL with the same body must produce the same final state.
• DELETE — idempotent. Deleting an already-deleted resource is a no-op; the resulting state is the same.
• HEAD, OPTIONS, TRACE — idempotent by definition (read-only).

Two methods are explicitly not idempotent by default:

• POST — not idempotent. Two POSTs to the same URL with the same body may create two distinct resources.
• PATCH — not idempotent in general. Depends on the patch operation; a JSON Patch with { "op": "add" } is not idempotent, while { "op": "replace" } is.

This matters because HTTP infrastructure (proxies, CDNs, browsers) sometimes retries requests automatically, but only on methods that are spec-defined as idempotent. A browser will re-issue a GET on a connection error; it will not re-issue a POST without prompting the user. So the spec already does some of the work for you on the read side. The write side — POSTs that create resources, PATCHes that modify state — is where you have to add idempotency by construction.

The idempotency key pattern

Stripe popularized the modern solution: every mutating request includes an Idempotency-Key header with a unique value (typically a UUID). The server stores the key alongside the resulting response for some retention period (24 hours in Stripe's case). On retry, the server sees the key, looks up the stored response, and returns it verbatim — without re-executing the operation.

The Stripe pattern in pseudocode:

The mechanics matter:

• The client generates the key. A UUIDv4 generated client-side, before the request is sent. The same key is reused for any retries of the same logical operation.
• The server stores key + response. Typically in a database table with the key as primary key and the response body and status code as columns. Stripe stores responses for 24 hours; you choose your own TTL.
• On match, return the stored response. Without re-executing the operation. This is the entire point.
• On match with a different request body, error. Stripe returns an error if the body for the same key differs — a signal that the key is being reused incorrectly.

Stripe's implementation is documented in their idempotent requests guide. The 24-hour TTL is long enough to cover any reasonable retry window; the constraint is that very late retries (a day after the original) are not protected.

Implementing idempotency keys yourself

For your own API endpoints, the simplest implementation is a dedicated table:

The handler logic:

1. Read the Idempotency-Key header from the request.
2. Look up the row in idempotency_keys.
3. If found and the request hash matches, return the stored response.
4. If found but the request hash differs, return a 422 error (key reused incorrectly).
5. If not found, execute the operation inside a transaction. Insert the row with the resulting response.
6. Return the response.

The trickiest part is step five: the operation and the idempotency-row insert must be atomic. If the operation succeeds but the row insert fails, the next retry will re-execute the operation. The fix is to wrap both in the same database transaction (when the operation is itself a database write) or to use a two-phase pattern (claim the key first, do the work, mark complete) when the operation involves an external system like a payment processor.

Idempotency by design vs idempotency via key

There are two fundamental approaches, and the right answer depends on the operation.

Idempotency by design

The operation is structured so that running it multiple times produces the same final state without needing a key. Examples:

• UPSERT instead of INSERT. “Insert a row, or update if it exists” is idempotent. Postgres INSERT ... ON CONFLICT DO UPDATE is the canonical SQL form.
• Conditional updates with a version check. UPDATE rows SET status = 'processed' WHERE id = ? AND status = 'pending' is idempotent — the second call updates zero rows, leaving the same final state.
• State-transition guards. “Set status to X if currently Y” is idempotent because the second call sees the state is already X and does nothing.
• Compute-from-input operations. If your handler reads the input, derives the result purely from the input, and writes the result with an UPSERT, the entire pipeline is idempotent.

Idempotency via key

The operation is unavoidably stateful and has external side effects that cannot be made idempotent through SQL alone. Examples:

• Charge a credit card. The card processor (Stripe) is the source of truth for whether the charge happened. The only way to retry safely is to send the same idempotency key on retry.
• Send a transactional email. The email provider does not know whether you sent this email already. You must track sent state yourself with a key.
• POST to an external webhook. The receiver may or may not be idempotent. The safer pattern is to track delivery state on your side keyed by an idempotency value.

The rule of thumb: when the side effect is internal (your own database), prefer idempotency by design. When the side effect is external (a third-party API call), use an idempotency key. Mix both when the operation does both.

Webhook receivers should always be idempotent

Stripe sends the same event multiple times by design. The Stripe webhook documentation is unambiguous: handlers must be idempotent because retries happen on the order of seconds (after a non-2xx response) or minutes/hours (during outage recovery). The same applies to webhooks from any provider that takes reliability seriously — Resend, Twilio, Slack, GitHub, Linear all retry.

The idempotency mechanism for webhooks is usually the event ID. Stripe events have a unique id field (e.g., evt_1NxYz...). The handler stores processed event IDs in a database table; on each invocation, the handler checks whether the event ID is already in the table and short-circuits if so. The two-row schema is enough:

The full handler pattern is in webhook security best practices. The short version: verify the signature, look up the event ID, return early if already processed, otherwise process and insert.

Cron jobs and background jobs

Vercel Cron documents at-least-once delivery: a cron job may be invoked more than once for the same scheduled time if the function times out or fails to acknowledge. The same applies to scheduled tasks on most platforms. The implication: every cron handler must be idempotent.

The natural keying strategy for cron jobs is the scheduled run timestamp. A daily-digest job that runs at 09:00 UTC can store a row keyed by ('daily-digest', '2026-05-08') when it begins, fail to insert if the row already exists, and short-circuit. Background job systems like Inngest and Trigger.dev expose the run ID directly, which can serve as the idempotency key.

Without this guard, a cron job that times out at minute four of a five-minute execution will be retried by the platform, re-execute from scratch, and either send duplicate notifications or perform duplicate writes. The fix is the same key + check pattern; the only thing that changes is the source of the key. See the cron-specific notes in how to set up cron jobs on Vercel.

The four common idempotency patterns

Pattern	How it works	Best for
UPSERT	INSERT ... ON CONFLICT DO UPDATE in SQL. Multiple calls converge to the same final row.	Sync operations from an external source of truth, idempotent by SQL semantics.
Lock + check	SELECT ... FOR UPDATE the row, check its state, conditionally update. Concurrency-safe.	State machines where transitions must happen exactly once.
Idempotency key table	Separate idempotency_keys table. Insert key + response on first call; return stored response on retry.	External API calls (payments, emails) where the side effect cannot be undone.
Outbox pattern	Write a record to an outbox table inside the same transaction as the business write. A separate worker reads the outbox and dispatches the side effect with retry-safe semantics.	Decoupling business logic from external dispatch, distributed-systems consistency.

Most solo SaaS apps end up using all four at different points in their architecture. UPSERTs for syncing data from third-party APIs, lock + check for in-app state machines, idempotency keys for payment endpoints, the outbox pattern for any piece of the system that needs guaranteed-once eventual delivery to an external system. The Stripe + Supabase subscription guide walks through several of these together in a working example.

Common idempotency mistakes

The same handful of mistakes show up over and over:

• Assuming HTTP retries do not happen. They do. Mobile networks, flaky WiFi, server timeouts, intermediate proxies — all sources of duplicated requests. Designing as if every POST happens exactly once leads to the double-charge bug eventually.
• Ignoring webhook signature validation. An idempotent handler that does not verify the webhook signature can be tricked into processing replayed events from an attacker. The two checks — signature and idempotency — are independent and both required.
• No DB transaction around state checks. The pattern “SELECT, check status, UPDATE” is racy. Two concurrent invocations both read “pending,” both decide to process, both update. Either use a transaction with row-level locking (SELECT ... FOR UPDATE) or rely on a conditional UPDATE that returns the affected row count.
• Idempotency key TTL too short. A 5-minute key TTL is fine for tight retry loops but breaks for retries that arrive an hour later (e.g., during outage recovery). A 24-hour TTL is the Stripe default for a reason.
• Reusing keys across distinct operations. Two different actions (cancel subscription, then create new subscription) should never share an idempotency key. Generate a new UUID per logical operation.
• Storing the request body but not the response. If a retry arrives, returning a 200 without the original response body breaks the contract — the caller expected the same payload it would have gotten on the first call.
• Forgetting that GET retries also matter. A handler that increments a counter on every GET request is not idempotent despite using the “idempotent” method. The HTTP spec gives a contract; your code has to honor it.

The takeaway

Idempotency is the property that lets you safely retry. Networks fail, webhooks redeliver, cron jobs reschedule, and modern infrastructure ships at-least-once delivery semantics on every async surface. Without idempotency, every one of those becomes a duplicate-charge bug or a duplicate-record bug waiting to happen. With it, retries are a non-event.

The implementation patterns are straightforward: design state changes around UPSERTs and conditional updates when you can; use idempotency keys for anything with external side effects; never trust a webhook to arrive exactly once; treat every cron and background job as if it might run twice. Build the table, store the keys, return the cached response on retry. The plumbing is unsexy but the absence of it is what turns a 2am pager alert into a refund flood.

Related patterns and primitives are covered in what is a webhook, webhook security best practices, and what is API rate limiting — the three companion concepts that show up in the same code paths as idempotency on most SaaS backends.