Skip to main content
Platform security guideReviewed

Stripe webhook security: signatures, replays, duplicates and rolled secrets

How Stripe signs the events it sends, what your handler has to check before it trusts one, and how to cope with stale, repeated and out-of-order deliveries.

With a fixture table, an endpoint register to fill in for your own account, and a local lab of invented test-mode events.

Stripe webhook fixture table, endpoint register and local lab

Part A is a fixture table covering valid, repeated, stale, altered, wrongly signed, unsigned, re-serialised, out-of-order, retried and rolled-secret deliveries, each with what Stripe's documentation says and what the lab did. Part B is an endpoint register to copy once per endpoint, Part C plans a secret roll without performing it, and Part D is the local lab of invented test-mode events with its captured output.

How to use it

Part B reads settings, files and lists, Parts B and C record secrets by name only, and Part D sends requests only to 127.0.0.1 or localhost.

stripe-webhook-security.txt

Introduction16 lines

HOW TO USE THIS SHEET Part A is the fixture table: one block per kind of delivery a handler has to cope with, giving what the fixture sends, what Stripe's documentation says, what the lab receiver in Part D did with it, and a line for your own copy. Part B is the endpoint register: copy it once for every webhook endpoint, in each sandbox and in live mode, and fill it from the screens and files each row names. Part C is the plan to have in writing before anyone rolls an endpoint secret. Part D is the lab itself. Rules for every part: 1. Names, never values. Never write an endpoint secret, an API key or a real event payload into this sheet. Record which variable holds a secret, where it is set and whether it is present. 2. Do not press "Reveal secret", "Click to reveal", "Roll secret" or "Resend" to fill this sheet. Stripe's pages describe each of them: the first two show a secret, rolling changes the endpoint's signing secret, and Resend delivers an event to your handler again. 3. Part B reads settings, files and lists, and Part C is lines to fill in. The only requests in this sheet are Part A's six S fixtures and the lab's RUN 1, and the sender in Part D refuses any address other than 127.0.0.1 or localhost. 4. Before you send the S fixtures to your own code, read the limits at the top of Part A. They go only to a local copy of your handler, started with the lab's invented secret and sandbox API keys, never live keys. "Source" names the page each line relies on. Stripe's pages were read on 15 November 2026 and WooCommerce's webhook page on 14 November 2026; where your integration uses an older library or a different event format, check the page again. "Lab" lines quote the captured output in Part D, which is an illustration and holds no code from Stripe's libraries. What is here: Part A Fixture table: blocks A1 to A11, matched to steps F1 to F13, R1 to R4 and S1 to S6 of the lab's RUN 1. Part B Endpoint register: rows B1 to B12, one copy per endpoint. Part C Secret-roll plan: what Stripe describes, then lines C1 to C6 to fill in. Part D Lab: four files, two runs and their captured output.

What a Stripe webhook endpoint is, and who can reach it

Stripe's documentation describes a webhook endpoint as a URL you register so that Stripe pushes real-time data to it when events happen in your Stripe account, and says it uses HTTPS to send webhook events to your app as a JSON payload.

Stripe gives examples of what this is for: responding when a customer's bank confirms a payment, when a customer disputes a charge, or when a recurring payment succeeds.

Stripe also says registered webhook endpoints must be publicly accessible HTTPS URLs. On this page's reading, that makes the route reachable by anyone who learns its address, not only by Stripe. Stripe's own warning is that, without verification, an attacker could send fake webhook events to your endpoint to trigger actions like fulfilling orders, granting account access, or modifying records.

For a Stripe Checkout integration, Stripe's fulfilment guide says webhooks are required for fulfilment: triggering it only from the checkout landing page is not enough, because customers are not guaranteed to visit that page. Stripe says you must use webhooks to make sure fulfilment happens for every payment, so the webhook handler is the code that triggers it.

This guide covers that handler: how it proves an event came from Stripe, refuses a stale one, acts on each event once, copes with events in any order and survives a rolled secret.

The API security guide covers the rest of an application's API, and the plugin library's page on the WooCommerce Stripe gateway covers where that plugin's webhook status is read.

What Stripe does, and what stays with your handler

What Stripe's documentation says Stripe itself does: it signs every webhook event by putting a signature in the Stripe-Signature header, generates a unique secret for each endpoint, generates a new timestamp and signature for each delivery attempt, retries deliveries that fail, and sends webhook events from a set list of IP addresses.

Stripe's pages on receiving events and on managing webhook endpoints give the integration a list of its own. Verify that events come from Stripe before acting on them. Pass the raw request body to verification untouched. Guard against duplicate receipts by logging the event IDs you have processed and not processing those already logged.

Make sure your destination does not depend on receiving events in a specific order. Return a 2xx quickly, before any complex logic that might cause a timeout. On this page's reading, each of those is code you write, deploy and keep running.

The endpoint register in this page's asset has a row for each item on that list, and each of its rows reads something on your side: a setting in your Stripe account, your deployment or your hosting, or part of your own code or runbook.

Stripe webhook signature verification: what is signed, and how to check it

The Stripe-Signature header holds comma-separated entries, including a timestamp and one or more signatures.

The t entry is the time Stripe signed the event, in seconds since the Unix epoch, and Stripe notes that it does not represent when the event itself was generated. Each v1 entry is an HMAC with SHA-256 that incorporates the event payload, the timestamp and the endpoint's signing secret, and a header can carry more than one.

Stripe's page, read on 15 November 2026, says the only valid live signature scheme is v1. For sandbox events it adds a signature with a fake v0 scheme, which is not valid for verification and which your code must ignore.

Stripe recommends its official libraries for the check: you pass the event payload, the Stripe-Signature header and the endpoint's secret, and a failed verification gives an error. Its page on managing webhook endpoints names the calls, constructEvent() for snapshot events and parseEventNotification() for thin events, and says each takes the raw request body, the header value and the endpoint secret.

For code that verifies without the libraries, Stripe sets out these steps. First, split the header on commas and each element on the equals sign, and keep the t value and every v1 value. Second, build the signed_payload string from the timestamp as a string, the character . and the unmodified request body.

Third, compute an HMAC with SHA-256, using an active endpoint signing secret as the key and signed_payload as the message. Fourth, compare the expected signature with every v1 signature using a constant-time string comparison; if one matches, reject the request when the difference between the current time and the received timestamp is outside your tolerance, and if none matches, reject it.

Debug entries that authenticate nothing

Stripe might add optional secret, destination and payload entries to help with debugging. The secret entry is a redacted representation of the endpoint's newest active signing secret, destination is the ID of the endpoint the secret belongs to, and payload is a suffix of the SHA-256 digest of the exact body that was signed.

Stripe says none of these entries is covered by the HMAC and that an attacker can construct debug values that match a forged request. To prevent downgrade attacks, it says to ignore signature schemes other than v1 and use only the t and v1 entries, and that your integration must accept unknown entries and must not depend on a fixed entry count or order.

On this page's reading, a parser that expects exactly one t and one v1 in a fixed position fails that last rule.

Why the raw body matters

Stripe requires the raw body of the request for signature verification, and says any manipulation of it causes verification to fail. Its page on managing webhook endpoints lists ways a framework can do that before your code sees the body: reordering keys, stripping whitespace, converting to JSON or changing encoding.

For stripe-node with Express it says app.use(express.json()) must appear after the webhook route, because Express applies middleware in order and would otherwise parse the body before verification.

The lab shows the failure from the other side. F8 sent a genuine, correctly signed event to a route that parsed the JSON and verified a re-serialised copy, and that route refused it with 400. F9 sent the same event to the route that verifies the bytes it received, which accepted it.

When genuine events fail verification, this page's advice is to give the check the raw bytes, never to switch the check off.

Stripe webhook replay protection: the signed timestamp

Stripe describes a replay attack as an attacker intercepting a valid payload and its signature, then re-transmitting them.

Its mitigation is the timestamp in the Stripe-Signature header. Because the timestamp is part of the signed payload, an attacker cannot change it without invalidating the signature, and if the signature is valid but the timestamp is too old, you can have your application reject the payload.

Stripe's libraries have a default tolerance of 5 minutes between the timestamp and the current time, and you can change it with an extra parameter when verifying. Stripe warns against a tolerance value of 0, which disables the recency check entirely, and says to use Network Time Protocol so your server's clock stays accurate and in step with Stripe's servers.

In the lab, F4 sent a correctly signed event whose signed timestamp was 600 seconds behind the sender's clock, and the receiver, set to the lab's own 300-second tolerance, refused it.

Stripe says it generates the timestamp and signature each time it sends an event, and that a retried event gets a new signature and timestamp. On this page's reading, a retry is therefore not refused for the age of the original event. On the same reading, the tolerance has a limit of its own: a captured delivery sent again within the window still verifies.

Stopping the same event being acted on twice, whatever its timestamp says, is the job of the event-id ledger in the next section.

Stripe webhook idempotency: acting on each event once

Stripe says webhook endpoints might occasionally receive the same event more than once, and that you can guard against duplicated receipts by logging the event IDs you have processed and not processing already-logged events.

It adds that in some cases two separate Event objects are generated and sent, and that you identify those duplicates by the ID of the object in data.object together with the event type. For Checkout, Stripe's fulfilment guide says the fulfilment function might be called multiple times, possibly concurrently, for the same Checkout Session, and must correctly handle being called multiple times with the same Checkout Session ID.

In its section on processing undelivered events, Stripe's page on managing webhook endpoints sets the order of work. Verify the webhook signature before checking whether you have already processed the event, and if you have, skip it and return a 200 response to stop further retries.

Its example marks an event as processing before the work and as processed after it, using functions you implement against your own data store. In the lab, F2 delivered F1's event again and got a 200 marked as a duplicate, and F3 sent a new event id for the same Checkout Session and got a 200 without a second fulfilment.

Two details decide whether a ledger holds, and both are this page's advice. The store has to refuse a second copy of an event ID by itself, such as through a unique constraint, because two deliveries that each check before either writes can both pass; the race conditions guide covers that pattern.

And the ledger entry needs a clear moment. The lab writes it only after the business step succeeds, so F12's failed first delivery left nothing behind and F13's retry was processed.

A processing mark written before the work needs a rule for work that died halfway, or every later delivery of that event is skipped.

A name clash is worth clearing up. Stripe's API also uses idempotency keys, but those make the requests your server sends to Stripe safe to retry without performing the same operation twice. The ledger here protects the other direction, the events Stripe sends to you, and the race conditions guide covers idempotency keys.

Out-of-order events: why created is not a sequence number

Stripe does not guarantee the delivery of events in the order they are generated.

Its example is a new subscription, which might generate customer.subscription.created, invoice.created, invoice.paid and charge.created if there is a charge. Stripe asks that your event destination not depend on receiving events in a specific order.

It is specific about the tempting shortcut. Snapshot events record created in seconds, so distinct events can share a timestamp, and Stripe says not to use created to determine event order or whether you have already processed an event; track event IDs to identify duplicate deliveries instead.

You can also use the API to retrieve any missing objects. Stripe's example is retrieving the invoice, charge and subscription objects with the information from invoice.paid, if that event arrives first.

Stripe's page also says a snapshot event handler can retrieve the API resource from the Stripe API to access the latest and up-to-date object definition, and the lab does that with an invented stand-in. F10 delivered a subscription snapshot saying active, then F11 delivered one saying past_due, standing for an earlier change that arrived late.

The receiver read the subscription's current state from its in-memory store both times, so the late snapshot did not set the subscription back to past_due.

In your own handler that read goes to Stripe's API and brings failure modes of its own, so this page's advice is to write a snapshot's fields directly only where the order of events cannot change the result.

Retries, response codes and recovering missed events

In live mode, Stripe attempts to deliver events for up to three days with an exponential back off, and it retries sandbox deliveries three times over the course of a few hours.

If the destination has been disabled or deleted when a retry is due, Stripe prevents future retries of that event, although a destination disabled and then re-enabled before Stripe is able to retry still sees future retry attempts. Resend on an event in the Dashboard works for up to 15 days after the event was created, and the Stripe CLI's stripe events resend command for up to 30 days.

Stripe says resending an event that failed to reach an endpoint does not cancel its automatic retries, even when the resend gets a 2xx.

Stripe treats a 200 as successful delivery and considers redirect responses to webhook requests failures. It says your endpoint must quickly return a successful status code before any complex logic that could cause a timeout, with the example of returning a 200 before updating a customer's invoice as paid in your accounting system.

It recommends processing incoming events with an asynchronous queue, and warns that a large spike in deliveries, for example at the beginning of the month when all subscriptions renew, might overwhelm your endpoint hosts. The lab processes each event before it answers, to keep the code short: F12 returned 500 when its invented downstream step failed, and the second delivery, F13, was processed.

On this page's reading, a design with a queue would carry that failure in the queue's own retry instead.

To speed up recovery after an endpoint was unavailable, Stripe's page on managing webhook endpoints describes listing events with delivery_success set to false and the event types your endpoint listens for, and notes that Stripe only returns events created in the last 30 days.

It warns that a recovery script might run more than once and that automatic retries might deliver some events while it runs. This page's advice is for the script and the handler to share one ledger.

The Stripe webhook secret: where it lives, and what rolling it changes

Stripe generates a unique secret for each endpoint.

If one endpoint is used with both test and live API keys, the secret is different for each, and with several endpoints you need a secret for each one you verify. The secret begins with whsec_. The Stripe CLI's stripe listen command prints a secret of its own for local testing, and Stripe's page on managing webhook endpoints says the most common cause of a signature verification error is using the wrong endpoint secret, adding that a CLI-forwarded endpoint's secret differs from a Dashboard-managed endpoint's.

An example on Stripe's page on managing webhook endpoints reads the secret from an environment variable called STRIPE_WEBHOOK_SECRET. The register in this page's asset records the variable's name and where it is set, never the value, and it uses neither "Reveal secret" nor "Click to reveal", which Stripe's pages describe for showing the secret.

The same page also suggests printing the endpointSecret value your code uses to compare it. The register leaves that out, because a printed secret can stay in terminal history or a log (this page's advice).

Stripe says the secret is modifiable in the Webhooks tab in Workbench, and recommends rolling it periodically or when you suspect it has been compromised. When you click "Roll secret" you can expire the current secret immediately or delay its expiration for up to 7 days, to allow time to update the verification code on your server.

During that time multiple secrets are active for the endpoint, and Stripe generates one signature per secret until expiration. Rolling changes the endpoint's signing secret, so the asset plans it rather than doing it.

The R steps of RUN 1 act this out with invented secrets. An event carrying a v1 signature for both secrets was accepted by receiver A, which held only the old secret (R1), and by receiver B, which held only the new one (R2).

Once only the new secret signed, receiver A refused the event with 400 (R3) while receiver B accepted it (R4). Taken with Stripe's statement that it generates one signature per secret until expiration, this page's reading is that a deployment can switch secrets at any point in the overlap, and one that has not switched when the old secret expires starts refusing genuine events. If a secret leaked, the secrets exposure guide covers the rest of the clean-up.

IP addresses, HTTPS, CSRF exemptions and who can change an endpoint

Stripe asks for IP allowlisting alongside signature verification: it sends webhook events from a set list of IP addresses, and suggests configuring your server or firewall to accept webhook requests only from them.

Its Domains and IP addresses page carries the list, offers it as text and JSON files for import into iptables or similar tools, and says Stripe gives seven days' notice through its API announce mailing list before changing its IP addresses. This page's advice is to name the person who receives that notice, because a rule nobody updates can start refusing Stripe after a change.

An HTTPS URL is required in live mode. Stripe says your server must be correctly configured to support HTTPS with a valid server certificate, and that its webhooks support only TLS v1.2 and v1.3. Frameworks such as Rails and Django might check every POST request for a CSRF token, which might stop legitimate events from being processed, so Stripe says you might need to exempt the webhooks route. Its Rails example exempts the webhook action alone. Keeping the exemption that narrow is this page's advice.

Stripe's page on managing webhook endpoints also covers who can change where your events go. The webhook_write permission, shown in the Dashboard as "Webhook Endpoints, Event Destinations: Write", can create or change destinations that subscribe to any event available on your account, and allows read access to any event notification payload and Event object, regardless of access to the object behind it.

Stripe recommends configuring destinations in the Dashboard and avoiding that permission where possible, and, where an integration needs it, isolating it in a dedicated restricted key protected as an administrative credential.

How to use the fixture table and the endpoint register

The asset has four parts, and it works best in this order.

  • Fill Part B, the endpoint register, once for every endpoint in each sandbox and in live mode, working from the screens and files each row names. Every row reads a setting, a file or a list. None asks you to reveal, roll or resend anything.
  • Read Part A beside it. Each block pairs what Stripe's documentation says about one kind of delivery with what the lab receiver did. Where a block has an S fixture, you can send that fixture to a local copy of your handler within the limits printed at the top of Part A. Where it has none, the block tells you what to read in your code.
  • Treat any row where your code contradicts the Stripe page it cites as a finding, such as a tolerance of 0, a JSON parser ahead of the webhook route, or a ledger check that runs before signature verification.
  • Fill Part C before anyone rolls an endpoint secret, and read the "Event deliveries" tab after the switch.
  • Fill the register again after a framework upgrade, a new endpoint or event type, a move to another host, or a secret roll.

The local fixtures, and what the runs showed

Part D is an illustration, not Stripe, and it holds no code from Stripe's libraries.

It is four small files: the invented values both sides share, a receiver, a sender and a script that runs them. Other than one another, the files import node:http and node:crypto only, and nothing needs installing. Each receiver asks for port 0 on 127.0.0.1, which leaves the choice of port to the operating system: Node.js's net documentation says that if the port is 0, the operating system will assign an arbitrary unused port, and its HTTP documentation says the HTTP server's listen() method is identical to the one in net.

The endpoint secrets are invented and deliberately not in the format of a real Stripe secret, every event is an invented test-mode event, and nothing is sent to Stripe.

It was written and run on Node.js v26.0.0 and on no other version, and a script pasted every output in Part D from the captured files.

The run Part D prints as RUN 1 sent 23 requests, each step once. F1 to F13 went to receiver A: a valid event, the same event again, a second event for the same Checkout Session, four deliveries a handler should refuse, the raw-body pair, the out-of-order pair and the retry pair.

R1 to R4 split the secret-roll deliveries between receivers A and B. S1 to S6 are the six fixtures the sender sends on its own, answered by receiver A, so there is a result to compare your own handler with. In RUN 2 the sender refused 203.0.113.10, an address other than 127.0.0.1 or localhost, before sending anything.

The receiver compares signatures with crypto.timingSafeEqual after checking that both are the same length. Node.js's crypto documentation describes timingSafeEqual as comparing the underlying bytes with a constant-time algorithm, and says it throws an error when the two values differ in byte length. It also says that using it does not guarantee the surrounding code is timing-safe.

What a review of your own endpoint cannot show

The register records how the endpoint is set up and how the code is written.

Several questions sit outside it.

  • Whether forged events were accepted before verification was in place. That needs your logs and your order records, and the register only says what is logged now.
  • Events Stripe never produced. Stripe documents that in rare cases it can fail to generate an Event object, which is then irrecoverable, and that it creates a health event instead, available as a public preview. Its advice, if your integration relies on the failed event type, is to poll the relevant API for the current state of the affected resource.
  • How the ledger behaves when two deliveries of one event arrive together. Reading the code shows the design; a test on a staging copy shows the behaviour.
  • What your systems do after the handler: emails, accounting entries, stock and access changes. The fixture table stops at the handler's answer.
  • Stripe's own platform. This page makes no statement about what Stripe allows a customer to test on systems Stripe runs; read Stripe's terms before sending test traffic to any of them.
  • If you think an endpoint secret or a key has already been misused, call an incident response specialist first: emergency incident response and round-the-clock monitoring are outside what Clever Ops provides. The security logging guide covers what to record for next time.

Where a Clever Ops test fits

This guide is for owners and developers checking their own Stripe webhook endpoint.

What Clever Ops tests is what customers reach through a browser or an API, and in a web application and API penetration test the payment work stays on your application's side, not on the provider's platform. A service another business runs, such as a hosted payment page, comes into scope only with its owner's agreement.

Within a scoped test, that payment work includes checking that an upgrade waits for the provider's confirmation of the payment, and that your notification route turns away a message whose signature does not verify.

It uses a staging copy connected to a non-live payment account wherever one exists, so no real card is charged.

Where the handler itself needs a closer look, the scope can add read-only access to the code for named areas such as the webhook handler. A secure code review is a separate piece of work that reads the source code its written scope names, through read-only access to your repository.

If Clever Ops built or hosts your application, the engagement is called a security review instead of an independent test, and the report records who built the application and who hosts it. For PCI work, Clever Ops is not a PCI Approved Scanning Vendor or a Qualified Security Assessor, so those scans and assessments are referred to a provider that holds the role.

A Clever Ops report is evidence for a decision that someone else makes, such as an auditor or a customer, and is not a certificate.

Bring the filled-in register to the scoping call. It shows which events your application depends on, where its secrets are set and how its handler treats a repeat, which is what a scope needs to decide what is in and what stays out.

Frequently asked questions

Each delivery carries a Stripe-Signature header with a t entry, the time Stripe signed the event, and one or more v1 entries. A v1 entry is an HMAC with SHA-256 over the timestamp, the character . and the unmodified request body, keyed with the endpoint's signing secret. Stripe's page, read on 15 November 2026, says v1 is the only valid live scheme, and that the fake v0 signature it adds to sandbox events must be ignored.

Stripe's libraries default to a tolerance of 5 minutes between the signed timestamp and the current time, and accept a different value as an extra parameter. Stripe warns that a tolerance of 0 disables the recency check entirely, and says to keep the server's clock accurate with Network Time Protocol. Stripe says a retried event gets a new timestamp and signature, so on this page's reading a long retry schedule does not call for a longer tolerance.

Stripe's page on managing webhook endpoints says the most common cause is the wrong endpoint secret: the secret printed by stripe listen differs from a Dashboard endpoint's secret, and Stripe's webhooks page adds that one endpoint used with test and live API keys has a different secret for each. A changed body also makes the check fail: Stripe requires the raw request body, and says some frameworks parse or mutate it by reordering keys, stripping whitespace, converting to JSON or changing encoding. For stripe-node with Express, express.json() has to come after the webhook route.

Yes. Stripe says endpoints might occasionally receive the same event more than once, and that you can guard against them by logging the event IDs you have processed and not processing those already logged. Stripe adds that in some cases two separate Event objects are generated and sent, which you identify by the ID of the object in data.object together with the event type. Stripe also says not to use the created field to decide whether an event was already processed.

In live mode, Stripe attempts delivery for up to three days with an exponential back off, and in a sandbox it retries three times over a few hours. Resend in the Dashboard works for up to 15 days after the event was created, and the CLI's stripe events resend command for up to 30 days. Stripe considers redirect responses failures, and its fix is to set the endpoint to the URL the redirect resolves to.

Stripe lets you expire the current secret immediately or delay its expiration for up to 7 days, and says that during that time multiple secrets are active and it generates one signature per secret until expiration. On this page's reading, a handler holding either secret can verify an event during the overlap, and once the old secret expires a handler still holding it refuses genuine events. The lab's R1 and R2 steps act out the first half with invented secrets, and R3 the second. Rolling changes the endpoint's signing secret, so plan which deployments need the new secret before you start.

Scope the right test for your application

Tell us what you have built, who uses it and when it needs to launch. You will get a plain-English recommendation: a website audit, a web application test or a referral to a specialist.