Clerk webhooks
Last verified against Clerk's documentation on September 27, 2026.
Clerk sends webhooks when something changes in your authentication data: a user signs up, updates their profile, joins an organization, or deletes their account. Most apps use them to keep a users table in sync with Clerk. The problems people hit are almost always the same three: auth middleware blocking the webhook route, a signature check against a parsed body, and code that expects the webhook to arrive before the user makes their next request. This page covers what Clerk sends, how it delivers, how to fix the common errors, and where HookDeploy fits.
What Clerk sends webhooks for
| Area | Key events | Typical use |
|---|---|---|
| Users | user.created, user.updated, user.deleted | Sync a users table, send welcome emails |
| Sessions | session.created, session.ended, session.removed, session.revoked | Audit sign-ins, react to revoked sessions |
| Organizations | organization.created, organization.updated, organization.deleted | Sync tenants |
| Memberships | organizationMembership.created, organizationMembership.updated, organizationMembership.deleted | Keep roles and team access in sync |
| Invitations | organizationInvitation.created, organizationInvitation.accepted, organizationInvitation.revoked | Track invites |
| Messages | email.created, sms.created | Deliver Clerk’s emails and SMS through your own provider |
Every webhook is a JSON POST with a type and the object under data.
How Clerk delivers webhooks
| Behavior | Detail |
|---|---|
| Delivery service | Svix |
| Signature headers | svix-id, svix-timestamp, and svix-signature |
| Signing scheme | HMAC-SHA256 over {svix-id}.{svix-timestamp}.{raw body}, keyed with your endpoint’s whsec_ secret |
| Timestamp tolerance | Five minutes |
| Success | Any 2xx within 15 seconds |
| Retries | Immediately, then 5 seconds, 5 minutes, 30 minutes, 2 hours, 5 hours, 10 hours, and 10 hours more |
| Manual replay | From the endpoint on the Webhooks page: one message, or every failed message since a date |
| Delivery guarantee | At least once. Deduplicate on svix-id |
| Consistency | Eventual. A webhook can arrive after the user’s next request |
| Source IPs | Svix publishes the IP addresses it sends from |
Common Clerk webhook errors and how to fix them
401s or redirects on the webhook route
Your auth middleware is treating Clerk’s request as an unauthenticated user. Webhooks don’t carry a session. Make the webhook path public in your middleware, and use one consistent path, such as /api/webhooks/clerk, in your code and in the Clerk Dashboard.
Signature verification fails
- The body was parsed first. The signature covers the raw bytes. Verify before any JSON middleware touches the request.
- Wrong secret. Each endpoint has its own signing secret, and development and production instances have separate endpoints.
- The timestamp is too old. Check your server’s clock. If it’s a retry or a replay, see Verifying late deliveries and replays.
New users missing from your database
Webhooks are eventually consistent, so a user can finish signing up and load your app before user.created arrives. Don’t make a synchronous flow like onboarding wait for a webhook. Read the current user from the session token or Clerk’s Backend API, and use webhooks for data the session doesn’t carry.
Duplicate users or double emails
Retries deliver the same event again. Deduplicate on svix-id, and write users with an upsert keyed on the Clerk user ID.
Updates applied out of order
A retried user.updated can land after a newer one. Compare the object’s updated_at with what you’ve stored before overwriting.
Why use HookDeploy with Clerk
Clerk already retries for about a day and lets you replay messages, so HookDeploy’s value here is about where events go and what you can see.
Send user events everywhere they’re needed
A new user often needs to reach your database, your CRM, your email platform, and your analytics. Point one Clerk endpoint at HookDeploy and forward each event to all of them in parallel. A failing destination doesn’t hold up the others. Free includes 1 destination per endpoint, Starter includes 5, and Pro and above are unlimited.
Sync users into private systems
The HookDeploy Agent connects outward from your network over mTLS and delivers events to a local port, so an internal database or admin service can follow Clerk without a public endpoint.
Inspect every event
See the exact body and headers of every delivery, alongside what your handler returned. A redirect from auth middleware shows up immediately as a 3xx or a login page in the response.
Develop against real events
A tap sends a temporary copy of live Clerk events to 127.0.0.1 on your machine while production keeps receiving them. Taps arrive in real time, so signatures verify within the five-minute window.
Know the trade-offs
- HookDeploy’s retries replace Clerk’s. Once HookDeploy responds, Svix stops retrying. Starter retries 3 times over about 35 minutes, and Pro and Scale up to 5 times on a schedule you choose, which is shorter than Svix’s schedule. Incidents and replay cover anything after that.
- Late deliveries and the signature window. Retries and replays that arrive more than five minutes after Clerk signed them fail the default check. Plan for that with the pattern below.
- Plan limits. On Free, requests beyond the monthly allowance or the daily limit get a
429, which Svix treats as a failed delivery and retries. Paid plans keep accepting traffic past the included volume.
Verifying late deliveries and replays
HookDeploy forwards Clerk’s original body and svix-* headers unchanged. Those headers are on HookDeploy’s protected list: they’re never redacted from stored requests, and header strip rules can’t remove them. So retries and replays carry a genuine signature, but one that’s older than five minutes rejects under the default check.
- Verify the HMAC on every request.
- If the timestamp is within five minutes, process it normally.
- If only the timestamp is stale, accept it only when the request carries an auth header you inject on the HookDeploy destination.
- Deduplicate on
svix-id. - For user and organization state, fetch the current object from Clerk’s Backend API before acting, so a late event never overwrites newer data.
Set up Clerk with HookDeploy
- In HookDeploy, create an endpoint (for example,
Clerk production) and copy its URL. - On the Forwarding tab, add a destination pointing to your handler, or to an agent for private delivery. Add a header
Authorization: Bearer YOUR_HANDLER_SECRET, and set the destination’s retries. - In the Clerk Dashboard, open Webhooks, add an endpoint with your HookDeploy URL, and subscribe to your events. Copy the endpoint’s signing secret.
- Send a test event from the endpoint’s testing tab, and confirm it appears in HookDeploy and reaches your handler.
Example handler (Node.js and Express)
import crypto from 'node:crypto';
import express from 'express';
const app = express();
const TOLERANCE_SECONDS = 5 * 60;
const secret = Buffer.from(process.env.CLERK_WEBHOOK_SIGNING_SECRET.split('_')[1], 'base64');
const hookdeployAuth = Buffer.from(`Bearer ${process.env.HANDLER_SECRET}`);
// Keep this route public in your auth middleware. Raw body parser, before any JSON middleware.
app.post('/api/webhooks/clerk', express.raw({ type: 'application/json' }), async (req, res) => {
const id = req.get('svix-id') ?? '';
const timestamp = req.get('svix-timestamp') ?? '';
const signatures = (req.get('svix-signature') ?? '')
.split(' ')
.map((part) => part.split(',')[1])
.filter(Boolean);
const expected = crypto
.createHmac('sha256', secret)
.update(`${id}.${timestamp}.${req.body.toString('utf8')}`)
.digest('base64');
const valid = signatures.some(
(sig) => sig.length === expected.length &&
crypto.timingSafeEqual(Buffer.from(sig), Buffer.from(expected))
);
if (!valid) return res.status(401).send('Invalid signature');
const fresh = Math.abs(Date.now() / 1000 - Number(timestamp)) <= TOLERANCE_SECONDS;
if (!fresh && !isFromHookDeploy(req)) return res.status(401).send('Stale signature');
res.sendStatus(200);
const event = JSON.parse(req.body.toString('utf8'));
await enqueue({ deliveryId: id, type: event.type, objectId: event.data?.id, fresh });
// Deduplicate on deliveryId (svix-id). For late events, fetch the object from Clerk's Backend API.
});
function isFromHookDeploy(req) {
const received = Buffer.from(req.get('authorization') ?? '');
return received.length === hookdeployAuth.length &&
crypto.timingSafeEqual(received, hookdeployAuth);
}
FAQ
How are Clerk webhooks signed?
Clerk sends webhooks through Svix, so every request carries svix-id, svix-timestamp, and svix-signature headers. Clerk's verifyWebhook helper checks them using your endpoint's signing secret, which it reads from CLERK_WEBHOOK_SIGNING_SECRET.
Why does verifyWebhook fail?
The usual causes are a body that was parsed before verification, the signing secret from a different endpoint or instance, or a request older than five minutes. Development and production instances have separate endpoints and separate secrets.
Why is my webhook route returning 401 or redirecting?
Your auth middleware is protecting it. Clerk's webhooks don't carry a user session, so the webhook route must be public in your middleware configuration. The signature check is what protects it.
Why isn't a new user in my database yet?
Webhooks are eventually consistent. A user can sign up and hit your app before the user.created webhook arrives. Clerk recommends reading the current user's data from the session token or the Backend API instead of waiting for a webhook in synchronous flows.
Does Clerk retry failed webhooks?
Yes. Clerk uses Svix's schedule, retrying immediately and then after 5 seconds, 5 minutes, 30 minutes, 2 hours, 5 hours, 10 hours, and 10 more hours. You can replay a single message, or every failed message since a date, from the Webhooks page.
Does HookDeploy break Clerk signature verification?
Not on first delivery. HookDeploy forwards the original body and svix headers unchanged, and those headers are never redacted or stripped. Retries and replays that arrive more than five minutes after Clerk signed them fail the default timestamp check.