# Webhook signing secret operations

## One secret per endpoint

When you create a webhook endpoint in the Dashboard (Webhooks page, Add Endpoint), Clerk generates a signing secret for that endpoint. Copy it into `CLERK_WEBHOOK_SIGNING_SECRET`.

Failure modes:
- Dev secret in production env (or vice versa): every event fails verification with a signature error. If verification fails everywhere after a deploy, compare secrets before debugging code.
- Recreating the endpoint generates a new secret. Deleting and re-adding an endpoint to "fix" delivery silently invalidates the old secret; update env at the same time.
- Multiple endpoints (dev tunnel, staging, prod) each have their own secret. There is no account-wide webhook secret.

## Rotation

Clerk's security guide covers rotating the secret key and webhook signing secrets. The flow: generate a new secret on the endpoint's settings page, update env, redeploy. During the window between rotation and deploy, events fail verification and Clerk retries them, so rotate during low traffic and deploy promptly. Retried events will verify once the new secret is live.

## Checklist

- Never commit the secret. It belongs in env vars on the host, same as the Clerk secret key.
- The endpoint URL must be exact: protocol, host (including www or not, exactly as the app serves), and path. A near-miss URL means events never arrive at all, which looks like a verification problem but is a routing one.
- Test from the endpoint's Testing tab with Send Example, and watch Message Attempts for Succeeded vs Failed before involving real user events.
- Return 2xx promptly. Slow handlers risk timeouts that Clerk counts as failures and retries.