Stripe webhooks in production: duplicates, ordering, retries and timeouts
This guide covers the problems Stripe webhooks cause in production and how to handle each one. What Stripe sends and how it's signed is on the Stripe webhooks overview, every event type is on Stripe webhook events, and signature verification code is on Verify Stripe webhooks.
At a glance
| Problem | What to do | With Event Gateway |
|---|---|---|
| Timeouts | Return a 2xx within a few seconds; process in a background job | Accepts the delivery at once, then queues it for your service |
| Duplicates | Record processed event ids; make handlers idempotent | Drops repeats before they reach your handler |
| Ordering | Fetch current state; don't order events by created | Logs every event and attempt, so you can see arrival order when debugging |
| Retries | Stay available; reconcile from the Events API after an outage | Accepts deliveries while your service is down and replays them |
| Choosing events | Subscribe only to the events you process | Filters and routes events by type |
| Testing | Forward events to localhost with a CLI | Forwards to localhost and replays past events |
| Other limits | Plan for 16 endpoints, delayed invoice events and API rate limits | Fans one endpoint out to many destinations at a rate you set |
Stripe webhook timeouts and slow handlers
Return a 2xx status within a few seconds, then do the work in a background job.
Why it happens: Stripe marks a delivery as failed if your endpoint doesn't respond quickly. It doesn't publish the exact limit, but it's a few seconds. Handlers that write to a database or call other APIs before responding exceed it. Each failure is queued for retry, adding load while your service is already struggling.
Fix it in your handler:
- Verify the signature and return 200 straight away.
- Push the event onto a queue (SQS, RabbitMQ or Redis) and process it in a worker (Sidekiq, Celery or Bull). See why to process webhooks asynchronously.
- Keep the request path free of calls to other services.
With Event Gateway: Hookdeck accepts each Stripe delivery immediately, then queues events and delivers them to your service at a rate it can handle, with its own retries. Your handler can take as long as it needs without failing a Stripe delivery.
Duplicate Stripe webhooks
Stripe can deliver the same event more than once. Record each event id you process and skip repeats.
Why it happens: Network timeouts, retries after slow responses and infrastructure issues all cause redelivery. Your endpoint may have processed an event and then returned a non-2xx status because of an unrelated error, so Stripe sends it again.
Fix it in your handler:
- Track processed event ids, using a database table with a unique constraint on the id.
- Make every handler idempotent: the same result however many times it runs.
- Wrap the side effect and the id record in one transaction.
def process_payment_webhook(payload):
event_id = payload['id']
# Check if we've already processed this event
if cache.get(f"stripe_event_{event_id}"):
return # Already processed
# Process the event
do_processing(payload)
# Mark as processed with TTL
cache.set(f"stripe_event_{event_id}", True, ex=86400)
With Event Gateway: Hookdeck deduplicates events before they reach your endpoint, so repeats are filtered at the infrastructure level rather than in each handler.
Out-of-order Stripe webhooks
Stripe doesn't guarantee delivery order. Rely on the object's current state, not arrival order or the event's created time.
Why it happens: Stripe uses at-least-once delivery and sends events concurrently, so a later event can arrive first. A customer.subscription.deleted event can arrive before customer.subscription.created. For more on the general problem, see Webhook Ordering: Why It's Hard and How to Handle It.
Fix it in your handler:
- Don't use
createdto decide what happened first. It's recorded in seconds, so distinct events can share a timestamp. - Use optimistic locking so an older event can't overwrite newer state.
- When an event is ambiguous, fetch the object's current state from the Stripe API.
- Write state transitions that tolerate events in any order.
With Event Gateway: Hookdeck logs every event and delivery attempt, so when state looks wrong you can see the order events actually arrived in and replay them.
Stripe webhook retries and disabled endpoints
Stripe retries failed deliveries for up to 3 days in live mode, then disables the endpoint. Keep the endpoint available and reconcile after any outage.
Why it happens: In live mode Stripe retries with exponential backoff: immediately, then after 5 minutes, 30 minutes, 2 hours, 5 hours and 10 hours, then every 12 hours, for up to 3 days. In test mode it makes three attempts over a few hours. After 3 days of continuous failures in live mode, Stripe disables the endpoint and sends you a notification. Events sent while the endpoint is disabled aren't redelivered, and there's no single request that returns everything you missed.
Fix it in your handler:
- Run webhook endpoints on high-availability infrastructure, with failover for critical ones.
- Monitor delivery failures in the Stripe Dashboard (Developers > Webhooks > Events), where you can also retry recent events by hand.
- Run periodic reconciliation jobs against Stripe's Events API to catch anything missed.
With Event Gateway: Hookdeck captures every Stripe delivery while your services are down, so Stripe's deliveries succeed and the endpoint isn't disabled. Failed events can be retried automatically, manually or in bulk once you recover.
Choosing which Stripe events to listen to
Subscribe each endpoint only to the events your integration processes, not to all events (['*']).
Why it matters: Every extra event type is a request your server has to accept, verify and discard. Stripe has hundreds of event types across payments, invoices, subscriptions and Connect; the full list, with sample payloads, is on Stripe webhook events. Stripe's thin events carry a reference rather than the full object; see Stripe thin events best practices.
Fix it in your handler:
- List the events your code handles and subscribe to exactly those.
- Use separate endpoints, with different signing secrets, for test mode and live mode.
- Validate the payload structure before using it, and ignore event types your handler doesn't expect.
def process_charge_event(payload):
# Validate required fields exist
if payload.get('type') != 'charge.succeeded':
return
charge = payload.get('data', {}).get('object')
if not charge:
logger.warning(f"Malformed charge event: {payload}")
return
# Process with confidence
amount = charge.get('amount')
# ...
With Event Gateway: Hookdeck filters and routes events by type, connected account or any other property, so one Stripe endpoint can feed several services.
Testing and debugging Stripe webhooks locally
Forward real Stripe events to your local server with a CLI rather than deploying to test.
Why it happens: Stripe needs a public HTTPS endpoint, and development machines sit behind NAT and firewalls. Test mode helps, but producing a specific sequence of events still means creating test data.
Fix it in your handler:
- Use the Stripe CLI to forward events to localhost, and its
triggercommand to generate specific events. - Keep fixtures of real payloads for edge cases; Stripe webhook events has sample payloads to start from.
- Test signature verification in every environment, not only locally.
With Event Gateway: The Hookdeck CLI receives webhooks on your machine without a public server, and you can replay past events with one click. See how to test and replay Stripe webhooks locally.
Other Stripe webhook limits
Plan for Stripe's endpoint limit, delayed invoice events, API rate limits and Connect routing before they reach production.
16 endpoints per account. Complex architectures run out of endpoints. Consolidate endpoints and route events internally, or point one endpoint at a router that fans events out.
Delayed invoice events. Stripe waits until one hour after the last webhook was successfully sent before sending invoice events, so they can arrive up to an hour late. Don't rely on immediate delivery for time-sensitive invoice processing; poll the API for critical operations.
API rate limits. Handlers that fetch the latest object from Stripe before processing multiply API calls, and under high volume they reach Stripe's rate limits (100 requests per second in live mode, 25 in test mode). Use the data in the payload where you can, cache objects, and queue API calls.
Traffic spikes. A billing run can send thousands of webhooks at once. Buffer them in a queue and scale workers horizontally.
Connect. Platforms receive their own account's events and their connected accounts' events. Route on the account id in the event, and keep account and Connect webhooks on separate routes.
With Event Gateway: Hookdeck sends one Stripe endpoint's events to as many destinations as you need, absorbs spikes in its queue, and delivers at a rate you configure, which keeps API calls from handlers below Stripe's limits.
Keep an outage from disabling your Stripe endpoint.
Hookdeck Event Gateway accepts every Stripe delivery, verifies its signature, queues events and retries to your service on your schedule.