# Stripe webhooks in production: duplicates, ordering, retries and timeouts

Agent skill: `npx skills add hookdeck/webhook-skills --skill stripe-webhooks` ([details](https://hookdeck.com/webhooks/stripe/skill))

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](/webhooks/stripe) overview, every event type is on [Stripe webhook events](/webhooks/stripe/events), and signature verification code is on [Verify Stripe webhooks](/webhooks/stripe/verify).

## At a glance

| Problem | What to do | With Event Gateway |
| --- | --- | --- |
| [Timeouts](#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](#duplicates) | Record processed event ids; make handlers idempotent | Drops repeats before they reach your handler |
| [Ordering](#ordering) | Fetch current state; don't order events by `created` | Logs every event and attempt, so you can see arrival order when debugging |
| [Retries](#retries) | Stay available; reconcile from the Events API after an outage | Accepts deliveries while your service is down and replays them |
| [Choosing events](#choosing-events) | Subscribe only to the events you process | Filters and routes events by type |
| [Testing](#testing) | Forward events to localhost with a CLI | Forwards to localhost and replays past events |
| [Other limits](#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 {#timeouts}

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:**

1. Verify the signature and return 200 straight away.
2. 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](/webhooks/guides/why-implement-asynchronous-processing-webhooks).
3. 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 {#duplicates}

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:**

1. Track processed event ids, using a database table with a unique constraint on the id.
2. Make every handler [idempotent](/webhooks/guides/implement-webhook-idempotency): the same result however many times it runs.
3. Wrap the side effect and the id record in one transaction.

```python
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](/docs/deduplication) events before they reach your endpoint, so repeats are filtered at the infrastructure level rather than in each handler.

## Out-of-order Stripe webhooks {#ordering}

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](/webhooks/guides/webhook-delivery-guarantees) 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](/webhooks/guides/webhook-ordering-why-its-hard-and-how-to-handle-it).

**Fix it in your handler:**

1. Don't use `created` to decide what happened first. It's recorded in seconds, so distinct events can share a timestamp.
2. Use optimistic locking so an older event can't overwrite newer state.
3. When an event is ambiguous, fetch the object's current state from the Stripe API.
4. 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 {#retries}

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:**

1. Run webhook endpoints on high-availability infrastructure, with failover for critical ones.
2. Monitor delivery failures in the Stripe Dashboard (Developers > Webhooks > Events), where you can also retry recent events by hand.
3. 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](/docs/retries) automatically, manually or in bulk once you recover.

## Choosing which Stripe events to listen to {#choosing-events}

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](/webhooks/stripe/events). Stripe's thin events carry a reference rather than the full object; see [Stripe thin events best practices](/webhooks/platforms/stripe-thin-events-best-practices).

**Fix it in your handler:**

1. List the events your code handles and subscribe to exactly those.
2. Use separate endpoints, with different signing secrets, for test mode and live mode.
3. Validate the payload structure before using it, and ignore event types your handler doesn't expect.

```python
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](/docs/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 {#testing}

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:**

1. Use the Stripe CLI to forward events to localhost, and its `trigger` command to generate specific events.
2. Keep fixtures of real payloads for edge cases; [Stripe webhook events](/webhooks/stripe/events) has sample payloads to start from.
3. Test signature verification in every environment, not only locally.

**With Event Gateway:** The [Hookdeck CLI](/docs/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](/webhooks/platforms/how-to-test-and-replay-stripe-webhooks-locally).

## Other Stripe webhook limits {#other-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.