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.