Guides · Updated October 23, 2026

Rotated your Stripe keys? Check your webhook secret

You rotated a Stripe key, or rolled a webhook secret, and everything looked fine. But if your server is still using an old or wrong whsec_… value, signature verification fails on every event. Stripe shows the deliveries as failed; your customers pay and nothing changes in your app. This guide shows how to tell which secret is which, fix it, redeploy, and recover the events you missed.

Two different secrets

Stripe keeps these separate (Stripe: API keys):

• API keys (sk_…, rk_…, pk_…) authenticate requests your server makes to Stripe.
• Webhook signing secrets (whsec_…) let your server check that a request from Stripe is genuine. Each webhook endpoint has its own, found in the Webhooks section of the Dashboard (Stripe: Webhooks).

So rotating or expiring an API key doesn't change any signing secret, and rolling an endpoint's signing secret doesn't touch your API keys. The trouble comes from the other direction: people rotate everything during a clean-up, paste values into the wrong variables, or roll the signing secret and forget that the server still has the old one.

How the signing secret ends up wrong

• You rolled the endpoint's secret. In Workbench, the overflow menu on an endpoint has Roll secret. You can expire the old secret immediately or let it live for up to 24 hours; while both are active, Stripe signs each event once per secret, so a server with either secret verifies fine (Stripe: Roll endpoint signing secrets). If you delay expiry and never update your server, it keeps working for a while and then starts failing when the old secret expires. That's a delayed failure, easy to miss.
• Test and live secrets are mixed up. Stripe generates a unique secret per endpoint, and an endpoint used with both test and live API keys has a different secret in each mode (Stripe: Retrieving your endpoint's secret). Live traffic signed with a test-mode secret fails, and vice versa.
• A Stripe CLI secret is deployed. The secret printed by stripe listen belongs to the CLI's forwarding, and is different from a Dashboard endpoint's secret. Stripe calls out mixing them up as the most common cause of signature errors (Stripe: Resolve signature verification errors).
• You have more than one endpoint. Each has its own secret. Using endpoint A's secret in the handler for endpoint B fails.
• The new variable was never deployed. You updated STRIPE_WEBHOOK_SECRET but the running deployment still has the old value (see the checklist below).
• Something else is wrong, not the secret. Stripe also lists a modified request body as a cause: the raw, unmodified body is required for verification, so a framework or middleware that parses it first will fail even with the right secret (Stripe: Check the request body).

The failure is quiet

Verification failure normally makes your handler return a 4xx, and nothing in your app crashes or alerts. From the founder's side, new subscriptions don't activate, cancellations and failed payments don't revoke access, and no one gets an error message. The only places it shows are the endpoint's Event deliveries tab in Stripe and your server logs.

In live mode, Stripe retries an undelivered event for up to three days with exponential backoff (Stripe: Automatic retries). Sandbox deliveries are retried three times over a few hours. So a short outage can heal by itself once the right secret is in place, and a longer one leaves events that need a manual resend.

Checklist

1. Find which secret your server is using

Look where the value is set: your host's environment variable settings for the production environment, and any .env file or secrets manager your deploy reads. Check the variable name your code actually reads (STRIPE_WEBHOOK_SECRET is common, but it's whatever you passed to the signature check) and which environment it's set for. On Vercel, for example, Production and Preview have separate values (Vercel: Environment variables).

2. Compare it with the right endpoint in Stripe

1. In the Dashboard, switch to the mode you're debugging (live or test/sandbox).
2. Open Workbench, then Webhooks, and select the endpoint whose URL is your production webhook URL. Check the URL carefully if you have more than one.
3. Click Reveal secret and compare it with your server's value.

Stripe's own advice is to print the secret your code uses and compare it. We'd rather you not write a full secret into logs. This temporary snippet shows enough to compare without exposing the value; delete it after use:

// Temporary, in your webhook route. Remove it after you've compared. Never log the full secret.
const s = process.env.STRIPE_WEBHOOK_SECRET ?? "";
console.log({
  set: s.length > 0,
  startsWithWhsec: s.startsWith("whsec_"),
  hasStrayWhitespaceOrQuotes: s !== s.trim() || /^["']|["']$/.test(s),
  length: s.length,
  last4: s.slice(-4),
});

Compare length and last4 against the revealed secret, and look for stray whitespace or quotes copied in with the value. If they differ, you've found it. If you can't tell, set the variable again from the Reveal secret value rather than trusting what's there.

3. Change the variable, then redeploy

Set the new value in your host's environment settings. Most hosts only apply environment variable changes to new deployments or restarts. Vercel's docs say changes aren't applied to previous deployments, only to new ones (Vercel: Environment variables). So trigger a redeploy (or restart) and confirm the new deployment is the one serving your webhook URL. If you have a Preview environment pointing a test endpoint at it, set that variable separately.

4. Send a test event

In a sandbox, trigger an event your endpoint subscribes to, for example stripe trigger payment_intent.succeeded (Stripe: Test your handler), and check that the endpoint's Event deliveries tab shows Delivered with a 200. For the sandbox endpoint, use the sandbox endpoint's secret. For live mode, rather than creating real charges, use the resend step below on a real failed event as your test.

5. Resend the events you missed

1. Find them. Open the endpoint's Event deliveries tab. It lists events as Delivered, Pending or Failed and shows the HTTP status of each attempt and when the next retry is due (Stripe: View event deliveries). Events marked Pending may still be retried automatically for up to three days in live mode.
2. Resend in the Dashboard. Open an event and click Resend. Stripe's docs say this works for up to 15 days after the event was created.
3. Or use the Stripe CLI. stripe events resend <event_id> --webhook-endpoint=<endpoint_id> works for up to 30 days after creation (Stripe CLI: events resend). The CLI makes sandbox requests by default; for live mode add --live.
4. List a whole backlog. The List Events API accepts delivery_success=false to return events that failed delivery to at least one endpoint, and only returns events from the last 30 days (Stripe: Process undelivered events, API: List events).

Two cautions from Stripe's docs. A manual resend doesn't cancel the automatic retries, so the same event can reach you twice; record processed event IDs and skip repeats (returning 200 to stop further retries). And Stripe doesn't guarantee event order, so don't assume a resent customer.subscription.updated is newer than your current data. If you can, set access from the subscription's current status fetched from the API, rather than from the event payload alone (Stripe: Event ordering).

6. Check your own data for the gap

Resending covers events Stripe still holds. Events older than the resend windows, or events your handler dropped for other reasons, can't be replayed. Find the time the secret went wrong (the first Failed delivery on the endpoint is a good marker) and look at everything that changed after it:

• New or reactivated subscriptions: active or trialing subscriptions created after that time whose user in your app is still on a free plan or locked out.
• Cancellations and failed payments: subscriptions that became canceled, unpaid or past_due after that time whose user still has access.
• Plan changes and seat quantity: upgrades, downgrades and quantity changes that your app never recorded.
• One-time purchases and refunds: Checkout payments that never granted access, and refunds that never revoked it.

For anything the resend didn't fix, compare the Stripe subscription or payment itself with your app's record and correct your data directly. The step-by-step method is in How to find Stripe customers who paid but don't have access.

Make it hard to miss next time

• Name the variable per mode and per endpoint if you have several, so test and live can't be swapped by accident.
• After any key or secret change, check the endpoint's Event deliveries tab a few minutes later and confirm new events show Delivered.
• When you roll a signing secret, keep the old one valid for the delay window Stripe offers, update and redeploy, and only then let it expire.
• Make the handler idempotent so manual resends and automatic retries are both safe.

PaidCheck can flag failed webhook events from the last 30 days and disabled endpoints with a Stripe-only check, and compare Stripe with who has access in your app. Paid plans run checks daily and send an alert email when a check finds a new issue. It can't see which secret your server uses; it shows you the effect.

FAQ