Clerk webhooks: verify the Svix signature, never trust the route alone

TL;DR

Use the svix-id header value as your idempotency key for the event. Only after verification succeeds, switch on evt.type and handle the event. Retries and replays reuse the same id. Pass the request through untouched. - Test with a bad signature and confirm a 400.

When to use

You are seeing this: Clerk delivers webhooks through Svix, signed with a per-endpoint signing secret. Use this skill when you run into "Clerk webhooks: verify the Svix signature, never trust the route alone".

When not to use

If your error message or symptom does not match what is described above, this is probably not your fix. Search for your exact error text instead of forcing this one to fit.

Versions

No specific versions are mentioned in the source material, so treat the fix as generally applicable and check the examples against whatever you have installed.

Verify every webhook

Clerk delivers webhooks through Svix, signed with a per-endpoint signing secret. Your handler must verify the signature before acting on anything. Forged events are trivial to send to an unverified endpoint.

What to do

1. In the Clerk Dashboard, open your webhook endpoint and copy the signing secret. Store it as an environment variable. Never commit it, never log it.
2. In your handler, call verifyWebhook from @clerk/nextjs/webhooks, passing the request directly. It reads the Svix headers (svix-id, svix-signature, svix-timestamp), checks the signature against the secret, and returns the typed event.
3. Only after verification succeeds, switch on evt.type and handle the event. If verification throws, return 400 and do nothing else.
4. Use the svix-id header value as your idempotency key for the event. Retries and replays reuse the same id.

The trap

Verifying "later." Agents sometimes wire the handler first and plan to add verification before launch. Every hour the endpoint is live and unverified, anyone can POST a fake user.created and create users in your database. Verification is step one, not polish.

Checklist

• Each endpoint has its own signing secret. Rotating or recreating the endpoint changes the secret; update the env var at the same time.
• verifyWebhook needs the raw request body. If your framework parses or transforms the body first, verification fails. Pass the request through untouched.
• Test with a bad signature and confirm a 400. A verification path you never tested is a verification path that might not run.

Clerk's verifyWebhook backend reference documents the verification function and its request shape. Verified live at https://clerk.com/docs/reference/backend/verify-webhook. The overview guide documents the Svix delivery model and the signing secret setup. Verified live at https://clerk.com/docs/guides/development/webhooks/overview.