How often should I rotate webhook secrets?

From the SoleOS answers series — written about our own product space; grounded in published definitions and documented behavior, never invented numbers.

Rotate webhook secrets on a fixed schedule (every 90-180 days is a reasonable default for a solo portfolio) and immediately whenever a trigger event happens — an employee/contractor offboarding, a leaked log, a suspicious payload, or retiring a tool that had access. The schedule catches the risks you don't know about; the triggers catch the ones you do.

If you run one product, this is a mildly annoying quarterly chore. If you run 10+ products across Stripe, Supabase, Firebase, and RevenueCat, it's a small operational system you need to actually maintain — because the failure mode isn't "someone hacks your webhook," it's "you forget which secrets are live and where, and one goes stale for eight months without anyone noticing."

What a webhook secret actually protects

A webhook secret (sometimes called a signing secret, like Stripe's whsec_...) lets your endpoint verify that an incoming request really came from the platform and wasn't forged. It doesn't grant read/write access to your account the way an API key does — its job is purely to authenticate the sender of an event, not to authorize what the receiver can do. That matters for how you think about risk: a leaked webhook secret lets someone send you fake events (e.g., a fake "payment succeeded" webhook), not pull your data or your customers' data out.

That's a real risk — fake events can trigger fulfillment, provisioning, or notifications you didn't earn — but it's a narrower blast radius than a leaked API key or OAuth token. Rotate both, but prioritize your differently: API keys and OAuth scopes first (see what SoleOS connects to for how scoped, revocable access should look), webhook secrets on a slightly longer but still fixed cycle.

A rotation schedule that survives a solo portfolio

Here's a default that doesn't require a compliance team to maintain:

• Every 90-180 days: rotate webhook secrets for anything processing payments or account state (Stripe, RevenueCat). Payments are the highest-consequence event stream in your stack.
• Every 6-12 months: rotate for lower-stakes signal webhooks (Supabase new-row triggers, Firebase auth events) — these usually just fire notifications, not money movement.
• Immediately, out of cycle: any time a contractor, freelancer, or agency who saw the secret stops working with you; any time you see an unexplained webhook call in your logs; any time you sunset a project (see the sunsetting checklist if you have one going away) and forget to kill its endpoints.

Write this on a calendar reminder, not in your memory. With one product, you'll remember. With five, you won't — and "I meant to rotate that" is how a stale secret survives two ownership changes and one departed contractor.

The actual rotation steps

Every platform's specifics differ, but the shape is the same:

1. Generate the new secret in the provider dashboard (Stripe: Developers → Webhooks → your endpoint → roll secret; Supabase: project webhook settings).
2. Deploy your endpoint to accept both secrets simultaneously for a short overlap window, if the platform supports multiple signing secrets per endpoint (Stripe does, via multiple webhook endpoint configs). If it doesn't, you'll have a few minutes of risk between "old secret invalid" and "new secret deployed" — schedule the swap for low-traffic hours.
3. Update the secret in your environment variables, not in code, and redeploy.
4. Confirm events are verifying successfully by checking your endpoint's recent delivery logs in the provider dashboard — most show signature verification failures explicitly.
5. Revoke the old secret once you've confirmed the new one is working end to end.
6. Log the rotation date somewhere — a spreadsheet row, a note, a ticket. Future-you needs to know when this last happened without reverse-engineering it from deploy history.

Step 4 is the one people skip and pay for later — a silent signature-verification failure means you stop receiving real events but the endpoint doesn't throw an obvious error, it just quietly returns a 400 that the provider retries and eventually gives up on.

What actually needs rotation vs. what you're overthinking

Not every credential in your stack is a webhook secret, and treating them all the same wastes your limited ops time.

• Webhook signing secrets (Stripe, Supabase, Firebase webhooks): rotate on the schedule above.
• API keys and service account keys (Play Console, App Store Connect p8 keys, Bing Webmaster): these authorize pulling data, so a leak has more read-access consequence. Rotate on offboarding and suspicion; a fixed calendar cycle is nice but less urgent than for payment webhooks.
• OAuth connections (GA4, Search Console, PostHog, RevenueCat via OAuth): you don't rotate these the same way — you revoke and re-grant. Check what's still connected every few months; see revoking a third-party app's access to your Google data if you've lost track.

If you're only using a metrics dashboard with read-only, revocable OAuth scopes, you genuinely have less to rotate — that's the whole point of scoped access over shared raw keys. This is worth checking regardless of what tools you use: the security overview covers how SoleOS scopes and revocation work if you're evaluating that model.

Where portfolios drift into risk

The single biggest reason indie founders miss rotations isn't laziness — it's that the secret lives in three places (a .env file, a deploy platform's environment variables, and maybe a serverless function config) and rotating it in only one place breaks production silently, so people stop rotating altogether to avoid the outage.

The fix isn't a fancier secrets manager necessarily — for 1-20 products, it's usually enough to:

• Keep one canonical list of every webhook endpoint you have, per project, with its last-rotated date.
• Store secrets in exactly one place your deploy pipeline reads from (not copy-pasted into multiple configs).
• Delete webhook endpoints for sunset or archived projects immediately, not "later" — a dead endpoint with a live secret is unmonitored risk for zero benefit.

None of this requires SoleOS or any other tool — it requires a checklist you actually follow. SoleOS doesn't manage or rotate your webhook secrets; it's portfolio intelligence for multi-product founders that reads aggregated metrics through OAuth or read-only keys (see the connectors page for exact scopes per integration), it doesn't touch payment webhooks or write access to your accounts. Disclosure: SoleOS wrote this post about its own space — connectors and credential hygiene are directly relevant to what we build, so take the framing with that in mind. If your real need is a secrets rotation calendar and a shared password manager, you don't need SoleOS for that; a spreadsheet and a recurring reminder will do it.

Frequently asked questions

Does rotating a webhook secret cause downtime?

Not if your platform supports multiple active signing secrets per endpoint during a transition (Stripe does). If it doesn't, there's a brief window where old-secret events might fail verification — schedule the swap for low-traffic hours and monitor delivery logs immediately after.

What's the difference between rotating a webhook secret and an API key?

A webhook secret verifies that inbound events came from the real platform; leaking it lets someone send you fake events. An API key authorizes outbound access to pull or push data; leaking it can expose real data. Prioritize API key rotation on offboarding, and keep webhook secrets on a calendar cycle.

Should I rotate secrets the same way across Stripe, Supabase, and Firebase?

The mechanics differ per dashboard, but the cadence logic doesn't have to. Treat anything touching payments (Stripe, RevenueCat) as higher priority for shorter cycles; treat pure signal webhooks (Supabase row triggers, Firebase auth events) on a longer cycle, and rotate everything immediately after a contractor offboarding or suspected leak regardless of schedule.

How do I know if a webhook secret leaked?

You usually won't know for certain — treat any exposure in logs, screen shares, shared repos, or a departing contractor's access as a leak by default and rotate rather than trying to confirm it. The cost of an unnecessary rotation is a few minutes; the cost of an unrotated leaked secret is open-ended.

Do I need to rotate secrets for tools I've disconnected?

You need to delete the webhook endpoint or revoke the key entirely, not just rotate it. A rotated secret still works — it's meant to keep working. If a tool is gone, remove its endpoint and its access outright; see revoking third-party access for the Google-specific steps.