SaaS & billing
If you are searching for stripe webhook retries, or for webhook idempotency, you are typically in one place: a customer was charged twice, access was flipped on twice, or an invoice was sent twice, and someone said 'Stripe sent the webhook twice'. The billing post is the org model, Customer Portal and what you need in place before the first paying customer. The rate-limit post is the cap on the expensive call. The transactional-email post is DNS and whether the mail lands. This one is replay. Stripe — and most PSPs — deliver at least once. A retry is not a new payment. It is the same event you did not 2xx, or that the network dropped. Without an event id you store before you touch money or access, a retry is another charge you call an accident.
A webhook endpoint that 'handles whatever comes in' is not a system. It is a side effect with a URL. Stripe sends again when you 5xx, when you time out, when you 2xx too late. You send again yourself when a job failed. The contract is at-least-once. The honest sentence is: this event can land twice, and the second time must be a no, we already did this. Without that sentence you have an endpoint. You do not have idempotency.
TL;DR
The main takeaways
- A retry is the same event. Without storing the event id first, the second delivery is a new charge you asked for.
- 2xx only after you have recorded the event. A 200 before the ledger is how you lose the event. A 500 after you charged is how you charge again.
- Idempotency is a row you own — event.id, processed_at — not a hope that Stripe 'probably only sends once'.
- Fulfilment (access, mail, invoice) reads the ledger. It does not create a new PaymentIntent because the webhook 'might have failed'.
- The billing post is org and portal. Rate-limit is the cap. Mail is delivery. This one is replay without a double side effect.
- You have handled retry when you can say: this event id can win only once. Not when the endpoint 'works in test'.
Why this matters at all
A SaaS that flips access on in the webhook and calls it done does not have 'simple billing'. It has a race. Stripe sends `invoice.paid`. You set a flag. You 500 because the mail failed. Stripe sends again. You set the flag again — or worse, you create a new charge 'so the customer is not stuck'. The customer is not stuck. The customer is charged twice. Support calls it Stripe. It is your handler that had no memory.
Teams do it because the first happy path worked. Checkout Session completed. Access on. Mail sent. The test was one request. No replay. No timeout. No 'we 200'd and crashed after'. Three paying customers later an event lands twice in three minutes, and you discover the entitlement table has no unique key on stripe_event_id. You fix that one customer. You do not touch the habit.
The damage is concrete. A double charge you refund in a panic. A double period stacked on a subscription. Two welcome mails. Two workspace provisions. A credit-note show you call 'Stripe was down'. Stripe was not down. Stripe did what the docs say: send again until you answer success. You did not answer success, or you answered success without writing the event down. Both are your job.
We write this because 'we have webhooks' has become a checkbox you tick when the URL is in the Dashboard. An honest setup is boring: store event.id, reject the duplicate, apply the side effect once, 2xx when the ledger knows the row. Without that you have an endpoint that does the right thing the first time. The first time is not the contract.
What a webhook retry actually is — and what an endpoint is not
A webhook retry is the same event, delivered again. Stripe, Adyen, Quickpay, your own internal bus — same contract: at least once. The event has an id. That id is the idempotency key you must not invent yourself when the provider already has one. Store it. If the row exists, you are done. If it does not, insert it and run the job. The difference is not whether you 'handle webhooks'. The difference is whether the second delivery is a no-op.
It is not the same as 'we verify the signature'. The signature says the payload is from Stripe. It does not say you have not seen the event before. You can verify correctly and still charge twice. The billing post is Customer, Subscription and org. This one is refusing to let a valid, signed event be a new business event just because it landed again.
It is also not the same as Stripe's Idempotency-Key on your outbound calls. That key is when you create a PaymentIntent and the network is unreliable. It belongs on the POST to Stripe. Webhook retry is the other direction: Stripe calls you. Two keys, two jobs. Setting Idempotency-Key on checkout and forgetting event id in the handler is locking one door and leaving the other open.
And it is not 'we always 200 so they stop sending'. A 200 before you have written the event is asking Stripe to stay quiet. If the process dies after 200, the event does not come again. Access never turns on. You have traded a double charge for a silent miss. The honest answer is: write the row (or a temporary 'received') in the same transaction as the 2xx you dare to promise. Failures after that are a job you retry yourself — not a new Stripe event you hope for.
What typically goes wrong when someone says the webhook is set up
The first failure is fulfilling in the handler without a unique row. You flip is_pro, you send mail, you provision. The event comes again. You flip, send, provision again. A unique key on user_id is not enough — the same user can have two genuine events. The key is event.id. User_id is who. Event.id is which event. The rate-limit post is how often someone may call you. This one is that the same caller with the same body must not count as two businesses.
The second failure is creating a new payment because the webhook 'failed'. invoice.payment_failed is not a signal to run PaymentIntent.create. It is a signal to show the customer an honest state and let Stripe retry collection under the policy you set in Billing. A handler that 'fixes' a failed event by charging again is a double charge with a name you call recovery.
The third failure is mixing event types into the same side effect. checkout.session.completed and invoice.paid and payment_intent.succeeded can all look like 'they paid'. If you turn access on for all three without a ledger check, Checkout and the first invoice have turned it on twice — or Checkout and a later invoice.paid have extended a period you already granted. Pick one source of 'paying'. The others are audit. The billing post is which model you choose. This one is that one event owns fulfilment.
The fourth failure is 2xx from a CDN or middleware before your code has run, or 500 on an event type you do not know and thereby asking for eternal retry of something you will never apply. Unknown type: log, store, 2xx. Known type, transient failure: 5xx, and the handler is idempotent. Known type, permanent (signature, parse): 4xx, and you have an alarm. A 500 on 'we do not know this type' fills the retry queue with noise until Stripe gives up — and then you have lost the events you actually needed.
Idempotent handler vs. 'we run whatever comes in'
Honest replay
Event.id in a unique row. Side effect once. 2xx when the ledger knows the event.
- Insert-ignore on event.id before access, mail or charge
- Fulfilment reads the ledger — does not create a new PaymentIntent 'just in case'
- 2xx after the row exists; 5xx only on a transient failure in a job that tolerates replay
- Is boring in test: the second request does nothing. That is the whole point
The hoped-for endpoint
URL in the Dashboard, happy path on click, and retry is 'Stripe spamming us'.
- Access flips per request, with no unique key on the event
- A failed webhook is 'fixed' with a new charge
- 200 is sent before the database, or 500 is sent after the charge
- Is an accident you call Stripe. The customer calls it two pulls on the card
// Right: event.id wins once. Retry is a no-op with 2xx.
async function onStripeEvent(event: { id: string; type: string }) {
const inserted = await db.stripeEvents.insertIgnore({ id: event.id, type: event.type });
if (!inserted) return; // already applied
await applyFromLedger(event); // never PaymentIntent.create "because retry"
}
// Wrong: the second delivery is a new business event
async function onStripeEventNaive(event: { id: string }) {
await stripe.paymentIntents.create({ /* new charge — a retry is now a second payment */ });
}How to make retry the same event — before you turn access on
Without this order you get another endpoint you call billing.
- 01
Store event.id in the same database as access, with a unique key
Not a cache that can be forgotten. Not 'we will check Stripe later'. A row that is either inserted or already there. If you cannot point at the table, you do not have idempotency. You have a hope that the network is polite.
- 02
Pick one event type that owns fulfilment
Typically invoice.paid or checkout.session.completed — not both as 'turn pro on'. The other types are log and state. The billing post is the subscription. This one is that two valid events are not two orders.
- 03
2xx when the row is yours, not when the HTTP call started
Write first. Answer after. Transient failure after insert: your job retries the side effect, Stripe should not. A 500 after a charge is the double charge you want to avoid. A 200 before insert is the silent miss you will not notice until the customer writes.
- 04
Never let the handler create a new payment 'because the first one failed'
Stripe retries collection on subscriptions under the policy you set. Your job is to mirror state. PaymentIntent.create in a webhook on a payment event is charging without the customer pressing anything. The transactional-email post is the receipt. This one is that the receipt must not become another pull.
- 05
Replay with the Stripe CLI and a stored event id before you call it done
Send the same event twice. The second time you should see a no-op and a 2xx. The first time you should see one row, one access, one mail. If the second looks like the first, you are not done. You have an endpoint that works in the test you did not run.
“You have handled retry when the same event id can charge only once — even when Stripe sends it again.”
Checkout, invoice, failed and mail — same word, four jobs
Checkout.session.completed is the job you typically turn access on for in an MVP. That is fine if it is the only source, and if session.id / event.id is stored uniquely. It rots when you also turn access on for invoice.paid for the same session, or when you create a subscription in the handler and let the first invoice.paid turn it on again. Choose. Checkout is 'they paid here'. Invoice is 'the period is paid'. They are not synonyms.
invoice.paid is the job a subscription lives on. Each paid period is an event. Unique on event.id, not on customer id. A customer id that is 'already pro' is not a no-op — next month is a new event that should extend, not be ignored. Conversely, a retry of the same invoice.paid is not a new period. The ledger tells them apart. A flag on the user does not.
invoice.payment_failed and payment_intent.payment_failed are the job you must not 'fix' with a new charge. Show the state. Send the mail the transactional-email post is about. Let Stripe retry under your Billing settings. An internal 'we will pull again now' from the webhook is another product you hid in an error handler. The rate-limit post is how often someone may hit you. This one is that you do not hit the customer again because you hit yourself.
Mail and provisioning are the job that makes you 500 after you have charged. Split them. The event is recorded. Access is on. Mail is a job with its own retry. If the mail fails, that is not Stripe's event that should land again. It is your queue. A 500 here is asking for another charge because the mail provider was slow. That is the wrong button.
What you should typically do in the situation you are in
Left is what you typically say. Right is the next step we typically recommend.
Situation
The customer was charged twice after 'Stripe sent the webhook twice'
Next step
Stop fulfilling per request. Unique on event.id. Refund the second. Replay twice in test before you call it closed
Situation
The handler creates a PaymentIntent when a failed event lands
Next step
Remove create. Mirror state. Let Stripe retry collection. Failed is not a signal to pull again yourself
Situation
Both checkout.session.completed and invoice.paid turn is_pro on
Next step
One type owns fulfilment. The other is audit. Two valid events are otherwise two turn-ons
Situation
You 200 at the start of the handler 'so Stripe is happy'
Next step
Write the event row first. 2xx after. An early 200 is a miss you do not get back
Situation
You 500 when mail fails, after access is already on
Next step
Mail is your job with its own retry. 2xx the event. A 500 here is the second charge you want to avoid
Checklist before you call the webhook idempotent
If you are missing several of these, the sentence the webhook is set up — the setup is an endpoint you are hoping for.
- You can point at a unique row for event.id in the same database as access
- A second delivery of the same event is a no-op with 2xx — you have seen it in replay, not in a hope
- No PaymentIntent.create or new charge inside the handler 'because it failed'
- One event type owns fulfilment. The others mirror or log
- 2xx means the row is yours. Mail and provision are your jobs, not Stripe's retry
- The billing post is org and portal. Rate-limit is the cap. Mail is delivery. This one is replay
Questions we get again and again
Is this the same as Stripe billing and org-auth, or as rate limiting?
No. The billing post is Customer, Subscription, organisation and who may do what in the product. The rate-limit post is the cap on login, search and expensive calls — how often someone may hit you. Transactional email is whether the receipt lands. This one is replay: the same event twice, without the second time becoming a new charge. You can have a clean org model and still turn access on twice. You can have a cap on the endpoint and still create two charges. They are four jobs. One does not replace the others.
Should we 200 immediately so Stripe does not retry?
Only when you have recorded the event. An early 200 is asking them to stay quiet before you know you can apply it. A timeout after 200 is a miss you do not get back. Write the row, 2xx, retry side effects yourself. A 5xx is right when you do not yet have the row and the failure is transient — and only if the handler tolerates running again. The goal is not to stop retries. The goal is that retries are harmless.
Is Stripe's Idempotency-Key enough?
It is enough for your outbound POST to Stripe: same key, same PaymentIntent, even if the network duplicates the call. It is not enough for the inbound webhook. Inbound events have event.id. That is the key you store. Two directions, two keys. Setting the header on checkout and forgetting the table on the webhook is locking the door you open and leaving the door Stripe knocks on wide open.
What about Quickpay, Adyen or a home-grown webhook?
The job is the same: an id you do not invent, a unique row, side effect once, 2xx when the row is yours. The field name changes. The contract does not. If the provider has no event id, you hash what you have (provider, type, business key) and treat the hash as the id — and you are honest that a field you chose is weaker than an id the provider guarantees. Do not invent a timestamp as the key. A timestamp is not identity.
May we refund automatically if we detect a duplicate charge?
A duplicate you created, you owe a fix. Automatic refund on 'we saw the event twice' is dangerous if you cannot tell replay from two genuine payments. The ledger tells them apart: the same event.id is replay; two event ids are two events. Refund the replay damage you made. Do not refund the other genuine period because you got scared. Support without a ledger is guessing. Guessing at money is the next duplicate.
If retry has become another charge you call Stripe
Let us separate a boring event id from an endpoint you are hoping for.
A unique row beats a handler that does the right thing the first time and the wrong thing the second.
