Skip to content
Tutorials Center
My learning

Topics

Lesson 24 of 38 ยท Webhooks

Webhook Retries and Ordering

Learn how Stripe retries failed webhook deliveries, why events can arrive out of order, how to fetch fresh state from the API, and how to acknowledge fast and process in a queue.

A webhook endpoint lives on a real server that restarts, overloads and sometimes returns errors. Stripe is built for that: if your endpoint does not answer with a 2xx status in time, Stripe retries the delivery, in live mode for up to three days using exponential backoff, and in test mode a few times over a shorter period. You can also resend any event by hand from the Dashboard.

Two practical consequences follow. First, a slow handler is as bad as a broken one. Second, retries and parallel deliveries mean events do not arrive in a guaranteed order. This lesson shows how to design for both.

What counts as a failure

  • Any status outside 2xx (including redirects).
  • No response before the timeout (a few seconds to tens of seconds; do not rely on the exact number).
  • A connection error or TLS failure.

Returning 500 for a bug is actually reasonable: Stripe will retry after you deploy the fix. Returning 400 for a bad signature is correct too. What you must avoid is returning a failure for an event you deliberately ignore.

Node.js Simulating retries with backoff

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

Acknowledge fast, process later

The safest endpoint does the minimum before replying: verify the signature, store the raw event, enqueue a job, return 200. A worker does the heavy lifting, retrying on its own schedule. If the worker fails, you still hold the event, so nothing is lost and Stripe is not involved.

flowchart LR
  S["Stripe"] -->|POST| E["Endpoint: verify + store"]
  E -->|200 OK| S
  E --> Q["Queue"]
  Q --> W["Worker: fulfil order, send email"]
  W --> DB[("Database")]

The endpoint answers before the slow work begins.

Node.js Endpoint replies first, worker finishes later

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

Events can arrive out of order

Stripe does not promise that customer.subscription.created arrives before invoice.paid, or that retries preserve order. A newly failed delivery can be retried after a later event was already processed. If you blindly apply every event, an old "status: past_due" can overwrite a newer "status: active".

Two defences work well:

  1. Compare timestamps. Each event has created. Store the created of the last event you applied to an object and ignore anything older.
  2. Fetch current state. Treat the event as a signal, then call the API (for example retrieve the subscription) and save what Stripe says now. This is slower but immune to ordering problems.
Node.js Ignoring stale events

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

Dependencies between events

Sometimes an event refers to an object you have not seen yet, such as an invoice.paid for a customer whose customer.created is delayed. Do not fail hard. Either fetch the missing object from the API, or return a failure so the delivery is retried later, once the other event has been processed.

Monitoring

Watch the webhook delivery log in the Dashboard, alert on repeated failures, and keep a way to replay stored events after a bug fix. Stripe disables endpoints that fail for many days, so silent failures eventually turn into lost updates.

Handlers that fetch fresh state from the API are the easiest to reason about. Use event data for speed and the API for truth when it matters, such as access to paid features.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. What happens if your endpoint returns 503?

    Any non-2xx result is a failed delivery, and Stripe retries with backoff.
  2. 2. Why should an endpoint enqueue work and reply quickly?

    Replying fast avoids timeouts. A worker can retry the slow work without Stripe's involvement.
  3. 3. Two events about the same subscription arrive in the wrong order. A good defence is to

    Timestamps or a fresh API read prevent an old status from overwriting a newer one.
  4. 4. An event refers to an object you do not know yet. What is a sensible response?

    Fetching the object or retrying later lets the dependency catch up without losing data.

Summary

  • Non-2xx responses and timeouts cause retries; live mode retries for days.
  • Verify, store, enqueue, reply 200; do slow work in a worker.
  • Events can be out of order: compare created or fetch fresh state.
  • Monitor the delivery log and keep the ability to replay events.

Next: Connect Account Types