Webhooks Aren't Notifications. They're Distributed Systems.

Here are a few lessons I learned while working with Stripe Webhooks in production.

⚡𝗬𝗼𝘂𝗿 𝗛𝗧𝗧𝗣 𝘀𝘁𝗮𝘁𝘂𝘀 𝗰𝗼𝗱𝗲 𝗶𝘀 𝘆𝗼𝘂𝗿 𝗿𝗲𝘁𝗿𝘆 𝗽𝗼𝗹𝗶𝗰𝘆.

Returning 200 tells Stripe the event was received and processed successfully. Stripe won't retry it again.

If your business logic fails, you should return a 5xx status code so that Stripe automatically retries the event delivery

⚡𝗧𝗵𝗲 𝗲𝘃𝗲𝗻𝘁 𝘆𝗼𝘂 𝗿𝗲𝗰𝗲𝗶𝘃𝗲 𝗶𝘀 𝗮 𝗵𝗶𝗻𝘁, 𝗻𝗼𝘁 𝘁𝗵𝗲 𝘁𝗿𝘂𝘁𝗵.

Webhook events may arrive late or out of order. Don't trust the payload. Refetch the current state from a source of truth and act accordingly.

⚡𝗗𝗼𝗻'𝘁 𝗱𝗼 𝘀𝗹𝗼𝘄 𝘄𝗼𝗿𝗸 𝗶𝗻𝘀𝗶𝗱𝗲 𝘁𝗵𝗲 𝗪𝗲𝗯𝗵𝗼𝗼𝗸 𝗲𝘃𝗲𝗻𝘁.

Stripe has a timeout threshold. If the endpoint doesn't respond quickly enough, Stripe considers it a failure and retries.

Process the slow work asynchronously outside the webhook handler.

Do you have any hard-learned lessons about Webhooks or Stripe? I'd love to know about that.

I share more engineering notes and production lessons on LinkedIn: Dipendra Neupane.

Comments

[challan116-ux]

Strong framing. In B2B EDI over AS2 we live this same problem wearing older clothes: when a functional acknowledgment (or MDN) goes missing, the sender can't tell whether the document processed or just vanished — so both sides need explicit acknowledgment semantics beyond the HTTP status. Separating ack from processing is the only approach that has ever actually worked for us.

[Muhammad Turner Gane]

good list. one i learned the hard way: returning 5xx is only safe if the retry can't double-apply. if the handler wrote half the access change before it threw, the retry runs on top of that. we record the event id in the same transaction as the access change, so a retry finds either nothing done or everything done. also worth testing what happens when stripe's retries run out, because after that nothing tells you again.