Skip to content
HookDeploy

Stripe webhooks

Last verified against Stripe's documentation on September 27, 2026.

On this page ↓

Stripe sends webhooks when something happens in your account: a payment succeeds, a subscription renews, an invoice fails, a customer opens a dispute. Most delivery problems come from a handful of causes: the wrong signing secret, a framework that changes the request body before verification, a handler that responds too slowly, or an endpoint that redirects. This page covers what Stripe sends, how it delivers, how to fix the common failures, and where HookDeploy fits.

What Stripe sends webhooks for

Stripe has hundreds of event types, grouped by the object they describe. These are the ones most integrations depend on.

AreaKey eventsTypical use
Checkoutcheckout.session.completed, checkout.session.async_payment_succeeded, checkout.session.async_payment_failedFulfill orders. Payment methods like bank debits confirm later, so listen for the async events too.
Paymentspayment_intent.succeeded, payment_intent.payment_failed, charge.refundedConfirm payments, handle failures, sync refunds
Subscriptionscustomer.subscription.created, customer.subscription.updated, customer.subscription.deleted, customer.subscription.trial_will_endGrant and revoke access, warn before trials end
Invoicesinvoice.created, invoice.paid, invoice.payment_failed, invoice.finalization_failedEdit draft invoices, confirm renewals, run dunning
Disputes and fraudcharge.dispute.created, radar.early_fraud_warning.createdRespond to chargebacks before the deadline, act on fraud warnings
Payoutspayout.paid, payout.failedReconcile money arriving in your bank account
Connectaccount.updatedTrack connected account onboarding and verification

Each event is a JSON POST containing an id, a type, a created timestamp, and the affected object under data.object. Stripe also offers thin events, which carry only an ID and type, and must be delivered to a separate endpoint. Your handler fetches the full object from the API.

Subscribe only to the events you handle. Stripe recommends against listening to everything, because the extra volume puts strain on your server.

How Stripe delivers webhooks

BehaviorDetail
Signature headerStripe-Signature, formatted t=<timestamp>,v1=<signature>
Signing schemeHMAC-SHA256 over {timestamp}.{raw body}, keyed with the endpoint’s whsec_ secret
Timestamp toleranceStripe’s libraries reject events signed more than 5 minutes ago by default
Automatic retriesLive mode: up to 3 days with exponential backoff. Sandbox: 3 attempts over a few hours
RedirectsAny 3xx response counts as a failed delivery
TLSTLS 1.2 or 1.3 required
OrderingNot guaranteed
DuplicatesPossible. The same event can arrive more than once
EndpointsUp to 16 webhook endpoints per Stripe account
Manual resendDashboard: up to 15 days after the event. Stripe CLI: up to 30 days
SecretsUnique per endpoint, and different in test and live mode
Source IPsA published list of 15 webhook IP addresses

Each retry gets a new timestamp and signature. If deliveries keep failing for several days, Stripe emails you and eventually disables the endpoint. A disabled endpoint receives nothing until you turn it back on.

Common Stripe webhook errors and how to fix them

“No signatures found matching the expected signature for payload”

This is the most common Stripe webhook error. One of the three inputs to verification is wrong: the body, the header, or the secret.

  • Wrong secret. Stripe says this is the most frequent cause. Every endpoint has its own whsec_ secret, test and live mode secrets differ, and stripe listen prints a separate secret for events it forwards. Make sure the secret belongs to the endpoint that sent the event.
  • The body changed before verification. Stripe signs the exact bytes it sends. If a JSON parser runs before your webhook route, such as a global express.json(), the body is re-serialized and the signature no longer matches. Give the webhook route a raw body parser, registered before any global JSON middleware.
  • The header was dropped or renamed. Proxies, load balancers, and some frameworks alter headers. Log the incoming Stripe-Signature value and compare it with what Stripe sent.

“Timestamp outside the tolerance zone”

The signature is genuine, but it was created more than 5 minutes before your server checked it.

  • Clock drift. Keep your server’s clock synced with NTP.
  • Late delivery. Queues, delayed retries, and manual replays can all deliver an event after the window closes. Don’t set the tolerance to 0: that turns off replay protection entirely. See Verifying late deliveries.

Timeouts

When your server takes too long to respond, Stripe marks the delivery as failed and retries it. The fix is structural: verify the signature, return 2xx right away, and process the event from a queue. Subscription renewals arrive in bursts at the start of each billing period, and that’s exactly when synchronous handlers fall over.

Redirects (3xx)

Stripe treats every redirect as a failure. The usual causes are HTTP to HTTPS redirects, www versus bare-domain redirects, and trailing-slash rewrites. Register the final URL exactly as your server serves it.

401, 403, 404, or 405

  • 401 or 403: authentication middleware or a firewall is blocking Stripe. Exempt the webhook route.
  • 403 from CSRF protection: Rails, Django, and similar frameworks reject POST requests without a CSRF token. Exempt the webhook route from CSRF checks.
  • 404 or 405: the route doesn’t exist at that path, or doesn’t accept POST.

TLS errors

Stripe couldn’t complete a secure connection, usually because of an expired certificate or a missing intermediate certificate. Run an SSL server test against the endpoint.

Duplicate or out-of-order events

Both are normal. Record each event id you’ve processed and skip repeats. Don’t use created to order events, since several can share the same second. If invoice.paid arrives before customer.subscription.created, fetch what’s missing from the API instead of waiting.

Invoices stuck in draft

If Stripe doesn’t get a successful response to invoice.created, it delays finalizing every invoice with automatic collection for up to 72 hours. That applies across all endpoints on your account, including third-party apps you’ve connected, so one failing endpoint can stall your entire billing run. After a successful response, Stripe waits about an hour before attempting payment.

Endpoint disabled

After several days of failed deliveries, Stripe disables the endpoint. Re-enable it in Workbench, then resend missed events from the Dashboard (within 15 days) or with stripe events resend (within 30 days).

Thin events hitting a snapshot handler

Thin events contain only an ID and type, and need their own endpoint. Handle them with your SDK’s event notification parser and fetch the full object when you need it.

Why use HookDeploy with Stripe

Stripe always gets a fast answer

HookDeploy captures each event at Cloudflare’s edge and responds to Stripe as soon as it’s captured, before forwarding it to your server. Slow handlers and outages on your side stop turning into Stripe timeouts, retry storms, disabled endpoints, or 72-hour invoice delays.

That moves your safety net. Once HookDeploy acknowledges an event, Stripe stops retrying it, so delivery to your server depends on HookDeploy:

  • Destination retries. Starter retries 3 times (after 30 seconds, 5 minutes, and 30 minutes). Pro and Scale retry up to 5 times on a schedule you choose. Free doesn’t retry automatically.
  • Incidents. Forward failures are grouped into incidents, and you can bulk-replay them at a controlled rate once your server recovers.
  • Invoice timing. If you edit draft invoices when invoice.created arrives, remember that Stripe moves toward payment about an hour after HookDeploy acknowledges the event, whether or not your server has processed it.

Your signature verification keeps working

On the first delivery, HookDeploy forwards Stripe’s original body and Stripe-Signature header unchanged, so your handler verifies exactly as if Stripe had called it directly. Stripe-Signature is on HookDeploy’s protected header list: it’s never redacted from stored requests, and custom header strip rules can’t remove it.

Know where verification stops working:

  • Late retries and replays. HookDeploy’s first retry, 30 seconds after a failure, lands well inside Stripe’s 5-minute window. Later retries and most manual replays arrive after it and fail the default timestamp check. See Verifying late deliveries.
  • Transformations. A transformation changes the body, so Stripe’s signature won’t match at that destination. Use transformations for destinations that don’t verify Stripe’s signature, and protect those with an injected auth header.
  • Privacy filters. Retries and replays send the stored copy of the request. If a privacy filter or body key sanitization changed what was stored, the signature won’t match on retry or replay.
  • Allowlisting Stripe’s IPs on your own server. Forwarded requests come from HookDeploy, not Stripe. Put the Stripe allowlist on your HookDeploy endpoint instead (the endpoint’s Security tab, then Network, where quick add includes all 15 of Stripe’s published webhook IPs), and rely on signature verification plus an injected header on your server.

One Stripe endpoint, many destinations

Stripe allows 16 webhook endpoints per account. Point one at HookDeploy and send every event to production, staging, Slack alerts, and your data pipeline in parallel. A failing destination doesn’t hold up the others.

Reshape Stripe payloads for other tools

Destinations that don’t verify Stripe’s signature, such as analytics, a CRM, or internal tools, can receive a reshaped payload. HookDeploy’s transformation editor can convert data.object.amount from cents with cents_to_currency, turn created into an ISO date with unix_to_iso, mask or hash a customer’s email, or use allowlist mode to forward only the fields a tool needs. Transformations are available on Starter and above.

No public URL for your handler

Stripe requires a publicly reachable HTTPS endpoint. With HookDeploy, that public URL belongs to HookDeploy. The HookDeploy Agent connects outward from your infrastructure over mTLS and delivers to a local port, so your Stripe handler has no public IP, open port, or exposed route.

Debug live Stripe traffic on your laptop

A tap sends a temporary copy of live Stripe events to 127.0.0.1 on your machine while production keeps delivering. Taps arrive in real time with Stripe’s original signature, so your local handler verifies them normally.

Inspect exactly what Stripe sent

Every captured event shows the raw body and headers as Stripe sent them. When verification fails in your app but the request looks right in HookDeploy, you know the problem is between your server’s edge and your handler.

Verifying late deliveries and replays

A retry or replay re-sends Stripe’s original body and signature. If it arrives more than 5 minutes after Stripe signed it, the default check rejects it with a timestamp error. The signature is still genuine; it’s just old.

The safe pattern treats a late webhook as a notification and asks Stripe for the truth:

  1. Verify the signature normally.
  2. If verification fails only on the timestamp, and the request carries HookDeploy’s x-hookdeploy-forward header and your injected auth header, take the event id from the body.
  3. Retrieve that event from Stripe’s API with your secret key, and process it, skipping any id you’ve already handled.

An event fetched from Stripe’s API with your secret key is authentic by definition, so this works for late deliveries of any age while Stripe still keeps the event.

Set up Stripe with HookDeploy

  1. In HookDeploy, create an endpoint (for example, Stripe production) and copy its URL.
  2. In the Stripe Dashboard, open Workbench, select the Webhooks tab, and click Create an event destination.
  3. Choose Your account, or Connected accounts for Connect. Select the API version and the events you handle, then choose Webhook endpoint and click Continue.
  4. Paste your HookDeploy URL as the Endpoint URL and create the destination. Click Reveal secret and copy the whsec_ signing secret.
  5. In HookDeploy, add a forward destination pointing to your handler, or to an agent for private delivery, and set its retries.
  6. On the HookDeploy endpoint, add Stripe’s IPs with Quick add. To also require HookDeploy’s secret token, add it to the URL you gave Stripe as ?token=, because Stripe can’t send custom headers. Anyone who can see your Stripe webhook settings can see that URL.
  7. Run stripe trigger payment_intent.succeeded and confirm the event appears in HookDeploy and reaches your handler.

Example handler (Node.js and Express)

import express from 'express';
import Stripe from 'stripe';

const stripe = new Stripe(process.env.STRIPE_SECRET_KEY);
const app = express();

// Register the webhook route with a raw body parser
// BEFORE any global app.use(express.json()).
app.post('/webhooks/stripe', express.raw({ type: 'application/json' }), async (req, res) => {
  let event;
  try {
    event = stripe.webhooks.constructEvent(
      req.body,                          // raw Buffer, untouched
      req.headers['stripe-signature'],
      process.env.STRIPE_WEBHOOK_SECRET  // this endpoint's whsec_ secret
    );
  } catch (err) {
    return res.status(400).send(`Webhook Error: ${err.message}`);
  }

  res.sendStatus(200);   // acknowledge first
  await enqueue(event);  // process asynchronously; skip event ids you've already handled
});

FAQ

Does HookDeploy break Stripe signature verification?

Not on first delivery. HookDeploy forwards Stripe's original body and Stripe-Signature header unchanged. Verification fails when a transformation changes the body, when a privacy filter changed the stored copy used for retries and replays, or when a retry or replay arrives more than 5 minutes after Stripe signed the event.

What happens to Stripe events when my server is down?

HookDeploy still captures them and responds to Stripe, so Stripe doesn't retry, disable your endpoint, or delay invoice finalization. Forwarding to your server fails and is retried on your destination's schedule. When your server is back, bulk-replay the failures from Incidents.

Can I receive Stripe webhooks on localhost?

Yes. Start a tap from the HookDeploy Desktop Agent or CLI to copy live events to a local port, or replay a captured event to your local handler. Your laptop never needs a public URL.

Do I still need the Stripe CLI?

It's still the easiest way to trigger test events with stripe trigger. You don't need to keep stripe listen running, and HookDeploy captures events even when your machine is off.

What happens if I hit my HookDeploy plan limit?

On the Free plan, HookDeploy returns 429 once the monthly allowance is used up. Stripe treats that as a failed delivery and retries on its normal schedule, so events aren't lost right away. Paid plans keep accepting events past the included volume and bill overage.

Does HookDeploy work with Stripe Connect?

Yes. Create an event destination with the Connected accounts scope and point it at a HookDeploy endpoint. Each event includes an account property identifying the connected account.

Capture Stripe webhooks free

Start free