Stripe Webhook

The Event object is a photograph, not a live feed

The single most useful thing to understand about a Stripe event is that it is frozen at the moment it was created.

The payload contains a data.object, which is the full API object as it existed when the event fired. Stripe is explicit that this never changes afterwards: the api_version field records the version used to render data when the event was created, and "The contents of data never change, so this value remains static regardless of the API version currently in use." Update your account to a newer API version and old events keep their old shape. Retrieve a two-week-old event with today’s API version and you still get the shape it was born with.

That is a feature when you want to know what happened, and a trap when you want to know what is true now. If a charge was created and then refunded four minutes later, the charge.succeeded event still describes an unrefunded charge, because that is what was true when it fired. Anything acting on stale event data rather than re-reading the object can post a record that was already obsolete when it arrived.

The other fields earn their place too. type names the event, like charge.succeeded or invoice.paid. livemode separates real activity from test activity, which matters more than it sounds because a test charge looks identical to a real one in the interface if you are not watching the mode toggle. request identifies the API call that caused the event, if there was one. pending_webhooks counts deliveries that have not yet succeeded. For a Connect platform, account names the connected account the event came from, which is the only thing distinguishing one seller’s activity from another’s.

Delivery is at-least-once, unordered, and retried for three days

Three properties of Stripe’s delivery model decide how an integration has to be built, and all three surprise people.

First, order is not guaranteed. Stripe states it directly: "Stripe doesn’t guarantee the delivery of events in the order that they’re generated." Creating a subscription can produce customer.subscription.created, invoice.created, invoice.paid, and charge.created, and they may arrive in any sequence. Stripe adds a second warning that catches people trying to sort their way out of it: snapshot events record created in seconds, so distinct events can share a timestamp, and "Don’t use created to determine event order or whether you’ve already processed an event."

Second, delivery is at least once, not exactly once. Stripe says endpoints "might occasionally receive the same event more than once" and recommends logging event IDs and skipping ones already seen. There is a subtler case too: sometimes two separate Event objects are generated for the same underlying change, and telling those apart needs the ID of the object in data.object together with the event type, because the event IDs differ.

Third, failure is patient. In live mode Stripe retries with exponential backoff for up to three days. In a sandbox it retries three times over a few hours. A retried delivery gets a fresh signature and timestamp, so a replay-protection window measured against the original timestamp will not reject it.

For bookkeeping, the practical consequence of all three is that duplicate protection cannot be an afterthought. An event arriving twice must not produce two sales receipts, and an event arriving late must not produce a record dated today for a sale that happened on Tuesday.

Signature verification, and the raw-body rule that breaks it

An unverified webhook endpoint is an open instruction channel. Anyone who learns the URL can POST a plausible JSON body and cause whatever the handler causes. Stripe puts the risk plainly: without verification "an attacker could send fake webhook events to your endpoint to trigger actions like fulfilling orders, granting account access, or modifying records."

The defence is the Stripe-Signature header. It carries a timestamp with a t= prefix and one or more signatures with a scheme prefix, of which v1 is the only valid live scheme. Stripe computes each signature as an HMAC using SHA-256, keyed on the endpoint’s signing secret, over a message built by concatenating the timestamp, a period, and the exact JSON request body. Verifying means recomputing that and comparing in constant time.

The timestamp is not decoration. Because it is inside the signed payload, an attacker cannot alter it without invalidating the signature, which is what makes it useful against replay attacks. Stripe’s libraries default to a five-minute tolerance and warn against setting the tolerance to zero, since that disables the recency check entirely rather than tightening it.

The failure mode almost everyone hits once is the raw body. Signature verification is computed over the bytes Stripe sent, so any middleware that parses JSON and re-serialises it, or that rewrites whitespace, produces a different message and a failed check. Stripe repeats the warning twice on its own page: "Stripe requires the raw body of the request to perform signature verification." A JSON body-parser mounted globally in a web framework is the usual culprit, and the symptom is every event failing verification while the payload looks perfectly correct in the logs.

Stripe recommends pairing signature verification with IP allowlisting, since webhook events come from a published set of addresses. Two independent checks, because either one alone can be misconfigured silently.

Why your endpoint must answer before it works

The instruction Stripe gives about response timing reads like a performance tip and is actually an architectural constraint.

Stripe asks endpoints to "quickly return a successful status code (2xx) before any complex logic that might cause a timeout", and gives an accounting example on its own initiative: you must return a 200 before updating a customer’s invoice as paid in your accounting system. If the handler waits, the delivery is recorded as a timeout and Stripe retries, which means the slow work now runs twice.

The shape that follows is a handler that verifies the signature, writes the event to a queue, and returns. Everything real happens afterwards, asynchronously. Stripe recommends exactly this, and points at the reason volume-driven businesses need it: a spike, such as the start of a month when every subscription renews, can overwhelm an endpoint that processes synchronously.

A few other delivery failures are worth recognising because they look like nothing is wrong. A 3xx redirect is treated as a failure rather than followed, so moving an endpoint and leaving a redirect behind silently stops delivery. A 4xx from access restrictions, or a 404, fails the same way. TLS below version 1.2 fails the connection outright. All of these appear in the Event deliveries tab of the endpoint in Workbench, with the HTTP status of each attempt, which is the place to look rather than the events list itself.

That distinction matters more than it sounds. The events list in your account records things that happened to your data, and those Event objects exist whether or not anyone is subscribed. Delivery is tracked separately, per endpoint. An event sitting in the list with no delivery row against a given endpoint was never sent there, and no amount of staring at the events list will show you that.