Stripe Webhooks
Stripe Webhook Best Practices: Return 2xx Immediately
Many webhook issues in Stripe integrations are caused by slow webhook handlers. If your endpoint does not return a successful 2xx response quickly, Stripe assumes delivery failed and retries the event.
Stripe webhooks notify your system about important events such as successful payments, subscription updates, and refunds. When Stripe sends an event to your webhook endpoint, it expects a confirmation that the event was received.
That confirmation is simply an HTTP response in the 2xx range. If Stripe receives it, the event is considered delivered.
If your server responds with anything else — or takes too long to respond — Stripe will attempt delivery again.
Why Stripe Requires a Fast 2xx Response
Stripe’s delivery system is designed to be reliable even when endpoints temporarily fail. When a request does not return a success status, Stripe assumes the event was not processed and schedules a retry.
This behavior protects against outages and network errors, but it also means slow webhook handlers can accidentally create duplicate processing.
For example, imagine a webhook handler that performs several database updates and API calls before returning a response. If that work takes too long, Stripe may retry the same event while the first request is still being processed.
The result can be duplicated actions such as sending multiple emails or recording the same payment twice.
The Wrong Way to Handle Stripe Webhooks
receive webhook verify signature run business logic update database call external APIs return HTTP 200
At first glance this looks reasonable, but it creates unnecessary risk. Any delay in the processing pipeline increases the chance of Stripe retrying the request.
A Safer Webhook Pattern
A more reliable pattern is to acknowledge the webhook immediately and process the event asynchronously.
receive webhook verify signature store event ID queue background job return HTTP 200
The webhook handler becomes lightweight and fast, reducing the chance of retries. All heavier work happens in background workers where failures can be retried safely.
Use Event IDs to Prevent Duplicate Processing
Even with a well-designed handler, duplicate deliveries can still occur. Stripe may resend events due to network issues or temporary outages.
To prevent problems, webhook handlers should store the event ID and ignore duplicates that have already been processed.
This approach ensures that even if Stripe retries an event, your application will not repeat the same operation.
Why Webhook Monitoring Is Still Important
Many webhook delivery problems go unnoticed because retries eventually succeed. Developers often assume everything is working while failures quietly happen in the background.
Monitoring webhook deliveries helps surface these hidden issues. Visibility into failed attempts, retry patterns, and delivery latency can reveal problems long before they affect customers.
WebhookWatch provides monitoring for webhook events across providers like Stripe, Paddle, and GitHub, helping teams detect failures and delivery incidents early.