Rotate a Stripe API key or webhook secret without breaking checkout

If the new signing secret isn't live on your server, your endpoint rejects events and they stay undelivered. CheckoutAlarm emails you at its next Stripe check (once a day on Free, hourly on Pro) when events are still undelivered after about 15 minutes. If you rotate the read-only key you gave CheckoutAlarm, it emails you that Stripe rejected that key, so you can paste the new one.

It never sees your server's own Stripe calls or your environment variables. If your app's secret key is wrong and every checkout fails, it only notices through the stalled-sales check, at its next Stripe check after 48 hours with no successful charges, and only if the previous 14 days had steady sales. A new store won't trigger it.

Free: 1 site, checked once a day. Pro: $19 a month, up to 3 sites checked hourly. You prove you own the site first. For Stripe we only take a restricted key with read access to Events, Webhook Endpoints and Charges. Full secret keys are refused. Compare plans

Publishable (pk_), secret (sk_) and restricted (rk_) keys are on the API keys page, with separate keys for sandbox and live mode. Stripe: API keys Your server uses the secret or restricted key to create Checkout Sessions.

Each webhook endpoint has its own whsec_ secret, which your server uses to check that an event came from Stripe. You roll it on the endpoint, not on the API keys page. Stripe: roll endpoint secrets Rotating API keys doesn't change it, so a leak of your environment variables means changing both.

Stripe says to rotate a restricted or secret key right away if it was exposed, even if you aren't sure anyone saw it. Stripe: handle compromised keys

On the API keys page, open the menu (⋯) next to the key, choose Rotate key, and pick an expiration. Copy the new key and save it: you can't see it again later. Stripe: rotate an API key

If you choose Now, the old key is deleted at once. Stripe: rotate an API key A call made with an expired key gets an authentication error, so checkout fails until the new key is deployed. Stripe: API keys If you choose a later time, both keys work for up to 7 days while you move over. Stripe: rotate safely

Put the new key in your host's environment variables and redeploy. On Vercel, a changed variable applies only to new deployments, not ones already running. Vercel: environment variables

Each key has request logs in Workbench. Stripe suggests expiring the old key only after its request volume has been at zero for a few hours or days. Stripe: view request logs Stripe: rotate safely

In Workbench, open the Webhooks tab, click the endpoint, open the menu (⋯) and click Roll secret. You can expire the current secret at once or delay it for up to 24 hours. While both are active, Stripe signs each event once per secret, so the old code keeps verifying. Stripe: roll endpoint secrets

Roll the secret on each endpoint whose secret may have leaked, and update the matching variable (often STRIPE_WEBHOOK_SECRET). Test and live endpoints have different secrets. More in works in test mode but not live.

Redeploy with the new secret inside the overlap. If the old secret expires first, your handler rejects every event with a signature error. That looks like signature verification failed.

Your endpoint's Event deliveries tab shows failed deliveries and when the next retry is. In live mode Stripe retries for up to three days. Stripe: automatic retries

Once the new secret is live, click Resend on a failed event in the Dashboard (up to 15 days after it was created), or use stripe events resend in the Stripe CLI (up to 30 days). Stripe: manual retries

Run one checkout end to end and confirm your app unlocked it. If it didn't, see paid but not unlocked.