Clerk webhooks

Watch Clerk user and session events arrive, and verify Svix signatures correctly.

Get a test URL

claude mcp add --transport http webhook-studio https://webhook-studio.com/mcp \
  --header "Authorization: Bearer $(curl -s -X POST https://webhook-studio.com/api/start | jq -r .api_token)"

Point Clerk at this URL

1. Create a test endpoint below and copy its URL.
2. In the Clerk Dashboard, open Configure → Webhooks → Add Endpoint.
3. Paste the Webhook Studio URL and subscribe to the events you want (start with user.created).
4. Copy the signing secret Clerk shows — it starts with whsec_.
5. Use the Dashboard's Testing tab to send a sample event, and watch it land in the Inbox.

What a Clerk delivery looks like

A representative body, using Clerk’s field names. Your own deliveries appear in the Inbox exactly as sent, headers and raw bytes included.

{
  "type": "user.created",
  "object": "event",
  "timestamp": 1721558400000,
  "data": {
    "id": "user_2abcDEF456ghiJKL789mnoPQR",
    "object": "user",
    "username": null,
    "first_name": "Alex",
    "last_name": "Rivera",
    "image_url": "https://img.clerk.com/preview.png",
    "has_image": false,
    "primary_email_address_id": "idn_2abcDEF456ghiJKL789mno",
    "email_addresses": [
      {
        "id": "idn_2abcDEF456ghiJKL789mno",
        "object": "email_address",
        "email_address": "alex@example.com",
        "verification": {
          "status": "verified",
          "strategy": "email_code"
        }
      }
    ],
    "public_metadata": {},
    "private_metadata": {},
    "unsafe_metadata": {},
    "created_at": 1721558397000,
    "updated_at": 1721558397000
  }
}

Delivery headers

Event types

The events worth handling first. See Clerk’s own documentation for the complete list.

Verify the svix-signature header

Clerk signs each delivery with HMAC-SHA256 over the raw request body, keyed on your webhook secret. Verify before you parse, and before you act.

import express from 'express';
import crypto from 'crypto';

const app = express();

app.post('/webhooks/clerk', express.raw({ type: 'application/json' }), (req, res) => {
  const id = req.get('svix-id');
  const ts = req.get('svix-timestamp');
  const header = req.get('svix-signature') ?? '';

  // Reject stale deliveries — the timestamp is signed, so this is meaningful.
  if (Math.abs(Date.now() / 1000 - Number(ts)) > 300) return res.sendStatus(401);

  // The secret is whsec_<base64>. Unlike Stripe's identically prefixed
  // secret, the bytes after the prefix are base64-DECODED to make the key.
  // Using the string as-is is the single most common Clerk verification bug.
  const key = Buffer.from(process.env.CLERK_WEBHOOK_SECRET.split('_')[1], 'base64');
  const expected = crypto
    .createHmac('sha256', key)
    .update(`${id}.${ts}.${req.body}`)   // id + timestamp + raw body
    .digest('base64');

  // During a rotation Svix sends old and new together; any match is valid.
  const ok = header.split(' ').some((part) => {
    const sig = part.startsWith('v1,') ? part.slice(3) : null;
    if (!sig) return false;
    const a = Buffer.from(expected, 'base64');
    const b = Buffer.from(sig, 'base64');
    return a.length === b.length && crypto.timingSafeEqual(a, b);
  });
  if (!ok) return res.sendStatus(401);

  res.sendStatus(200);
  const event = JSON.parse(req.body);
  // if (event.type === 'user.created') provision(event.data.id)
});

Retries and delivery guarantees

Clerk delivers through Svix, which retries on this schedule: immediately, then 5 seconds, 5 minutes, 30 minutes, 2 hours, 5 hours, 10 hours, and 10 hours again — 8 attempts over roughly 32 hours. Success is any 2xx within about 15 seconds. If every delivery to an endpoint fails over a 5-day window, Svix disables the endpoint and notifies you. Delivery is at-least-once and unordered, so deduplicate on svix-id.

Common pitfalls

FAQ