Stripe webhooks arrive twice or out of order. How do I handle them safely?
Treat every webhook as "something changed, go check." Verify the signature on the raw body, store each event ID so a repeat does nothing, return a 2xx fast, and fetch the current object from Stripe instead of trusting arrival order. Duplicates and shuffled order are documented behaviour, not a bug in your setup.
Cite
GitShowcase Forum, "Stripe webhooks arrive twice or out of order. How do I handle them safely?", https://gitshowcase.com/forum/discuss/stripe-webhooks-arrive-twice-or-out-of-order-how-do-i-handle-them/, accessed 2026-11-17.- Nils HaugenStaffAPIs and tooling editor: LLM, MCP, payments and portfolios ·
What Stripe actually promises
The Stripe webhooks docs are direct about this, as of the docs in November 2026:
- Endpoints might occasionally receive the same event more than once.
- Stripe does not guarantee events arrive in the order they were generated. Creating a subscription, for example, can produce
customer.subscription.created,invoice.created,invoice.paidandcharge.createdin any order. - In some cases two separate Event objects are generated for the same thing.
- Failed deliveries are retried automatically, in live mode for up to three days with exponential backoff.
So your handler has to be safe to run twice and safe to run in any order. The rest of this answer is how.
Check first
- What status code does your endpoint return? Anything other than 2xx, a redirect, or a slow response counts as a failure and triggers a retry. The docs treat 3xx as failures too.
- Does your framework parse the body before Stripe verification? Stripe needs the raw body, and any manipulation makes signature verification fail.
- In Workbench, open your endpoint's Event deliveries tab. It shows each event as Delivered, Pending or Failed, with the HTTP status of each attempt.
Step 1: Verify the signature on the raw body
Never act on an unverified request. A fake request could otherwise fulfil orders or grant access. Use the official library with the
Stripe-Signatureheader and your endpoint secret (it starts withwhsec_):import express from "express"; import Stripe from "stripe"; const stripe = new Stripe(process.env.STRIPE_API_KEY); const app = express(); // raw body for this route only app.post("/webhook", express.raw({ type: "application/json" }), async (req, res) => { let event; try { event = stripe.webhooks.constructEvent( req.body, req.headers["stripe-signature"], process.env.STRIPE_WEBHOOK_SECRET // whsec_... from your endpoint settings ); } catch (err) { return res.status(400).send("bad signature"); } // steps 2 to 4 go here });If this fails with a signature error, the usual cause is a JSON body parser running before this route. Each endpoint has its own secret, and test and live secrets differ.
Step 2: Make the handler idempotent with the event ID
Idempotent means running it twice has the same result as running it once. Stripe's advice is to log processed event IDs and skip repeats. The cleanest way is a table with a unique key, written in the same database transaction as your business change:
CREATE TABLE processed_events ( event_id text PRIMARY KEY, event_type text NOT NULL, received_at timestamptz NOT NULL DEFAULT now() );const client = await pool.connect(); try { await client.query("BEGIN"); const ins = await client.query( "INSERT INTO processed_events (event_id, event_type) VALUES ($1, $2) ON CONFLICT DO NOTHING", [event.id, event.type] ); if (ins.rowCount === 1) { await applyEvent(client, event); // your business logic } await client.query("COMMIT"); } catch (e) { await client.query("ROLLBACK"); return res.status(500).send("retry me"); // Stripe will retry } finally { client.release(); } res.status(200).send("ok");If the logic fails, the rollback also removes the event ID, so the retry runs it properly. For the "two separate Event objects" case, the docs suggest identifying duplicates with the ID of
data.objectplusevent.type. A unique key on that pair in your own domain table (for example one fulfilment per payment intent) is stronger than any event log alone.Step 3: Do not depend on order
Do not use the event's
createdtime to decide which came first. The docs warn that snapshot events recordcreatedin seconds, so distinct events can share a timestamp. Instead:Problem Safe approach invoice.paidarrives beforecustomer.subscription.createdOn each event, retrieve the current subscription from the API and write that state An old event arrives after a newer one Write the latest fetched object, never the stale payload A related row does not exist yet Return 500 so Stripe retries, or fetch and create it The docs also note you can retrieve missing objects through the API, for example the invoice, charge and subscription from
invoice.paid. In short: use the webhook as the trigger and the API as the source of truth.Step 4: Answer fast and process off the request
Return the 2xx before slow work such as emailing or updating a third party. The docs recommend handling events through an asynchronous queue, because a spike (for instance when many subscriptions renew at once) can overwhelm a handler that does everything inline. The pattern: verify, record the event ID, put a job on a queue, return 200.
Test it
Use the Stripe CLI to forward and replay events locally:
stripe listen --forward-to localhost:4242/webhook stripe trigger payment_intent.succeeded stripe events resend <EVENT_ID> --webhook-endpoint=<ENDPOINT_ID>Resend the same event twice and confirm your database changed once. The docs say manual resend works for up to 15 days in the Dashboard and 30 days with the CLI. For your own API calls, such as creating a charge from a worker that might retry, use an idempotency key so a retry cannot create a second object. The payment API guide compares providers. If your handler writes to a serverless database, the connection advice in Serverless Postgres keeps running out of connections applies here too.
Write something first.
Give people something to work with: at least 30 words on what happened and what you tried.
That is too long. Keep it under 6,000 characters.
Write the question as the title, 15 to 140 characters, no links.
Pick a category.
Add a name (2 to 40 characters, no links).
That email address does not look right.
That was quick. Read the thread, then try again.
The form expired. Reload the page and post again.
Something went wrong with the form. Reload and try again.
Please complete the check and post again.
Limit reached for now. Try again later.
This thread is closed to new replies.
This thread no longer accepts replies.
Something went wrong with the form. Reload and try again.
Post a reply or question first (name and email), then this browser can vote, edit and accept answers.
You cannot vote on your own post.
Only the author (within 30 days) or the forum team can do that.
That email already has an account. Use your sign-in link instead.
New accounts are paused for the moment. Try again later.
That was already posted.