Clerk Webhook: Example Payload, Headers and Signature

What is a Clerk webhook?

A Clerk webhook is an HTTP POST sent to an endpoint you registered for an application instance when something changes in it: a user signs up, updates their profile or is deleted, a session starts or ends, an organization or membership changes, an email or SMS is sent. Its usual job is keeping your own database in step with Clerk's user records.

The body is a compact envelope. type names the event, object is always event, and data is the resource in the same shape the Backend API returns. Delivery itself is handled by Svix, which is why the identifying and signing headers are prefixed svix- rather than clerk-.

What a Clerk webhook request looks like

The request line and headers as they reach your server, followed by the body. Ids, tokens and the signature are placeholders.

POST /your/webhook/path HTTP/1.1
Host: your-server.example
svix-id: msg_2abcEXAMPLE0000000000000001
svix-timestamp: 1767225600
svix-signature: v1,g0hM9SsE+OTPJTGt/tmIKtSyZlE3uFJELVlNIOLJ1OE=
Content-Type: application/json
User-Agent: Svix-Webhooks/1.0

{
  "type": "user.created",
  "object": "event",
  "timestamp": 1767225600000,
  "data": {
    "id": "user_2abcEXAMPLE0000000000000001",
    "object": "user",
    "first_name": "Ada",
    "last_name": "Lovelace",
    "username": null,
    "primary_email_address_id": "idn_2abcEXAMPLE0000000000000002",
    "email_addresses": [
      {
        "id": "idn_2abcEXAMPLE0000000000000002",
        "object": "email_address",
        "email_address": "ada@example.com",
        "verification": {
          "status": "verified",
          "strategy": "email_code"
        }
      }
    ],
    "external_id": null,
    "public_metadata": {},
    "created_at": 1767225599000,
    "updated_at": 1767225599000
  }
}

A user has a list of email addresses, not a single field; the one to use is the entry whose id equals primary_email_address_id. Timestamps inside the body are in milliseconds, while the svix-timestamp header is in seconds. A user.deleted event carries only the id and a deleted flag, since the rest of the record no longer exists.

Headers Clerk sends

Header names are case-insensitive. Your framework may show them lower-cased, and HTTP/2 always does.

How a Clerk webhook is signed

Each endpoint has a signing secret that starts with whsec_. The part after that prefix is base64, and the HMAC key is the decoded bytes, not the text you see. The signed content is the message id, the timestamp and the raw body joined by full stops: {svix-id}.{svix-timestamp}.{body}. The HMAC-SHA256 of that, base64-encoded and prefixed v1,, is what appears in svix-signature.

The header can hold several signatures separated by spaces, which happens while a secret is being rotated; accept the request if any one matches. Reject timestamps more than about five minutes from your clock. Clerk's SDKs and the Svix libraries do all of this for you, and the function below shows what they do. Compute it over the raw request body exactly as received — before any JSON parsing — and compare with a constant-time function.

const crypto = require('crypto');

// rawBody: string of the body exactly as received
// headers: lower-cased request headers
function verifyClerk(rawBody, headers, secret, toleranceSec = 300) {
  const id = headers['svix-id'];
  const ts = headers['svix-timestamp'];
  const given = String(headers['svix-signature'] || '').split(' ');
  if (!id || !ts) return false;
  if (Math.abs(Date.now() / 1000 - Number(ts)) > toleranceSec) return false;

  const key = Buffer.from(secret.replace(/^whsec_/, ''), 'base64');
  const expected = 'v1,' + crypto.createHmac('sha256', key)
    .update(id + '.' + ts + '.' + rawBody).digest('base64');
  const b = Buffer.from(expected);
  return given.some((s) => {
    const a = Buffer.from(s);
    return a.length === b.length && crypto.timingSafeEqual(a, b);
  });
}

Retries, ordering and the delivery log

Any 2xx within the timeout counts as delivered. Otherwise the message is retried on a fixed schedule that starts within seconds and stretches to gaps of several hours, ending roughly a day after the first attempt, per Svix's documentation at the time of writing. Every attempt keeps the same svix-id and gets a fresh timestamp and signature. An endpoint that fails continuously for days can be disabled.

Events are not guaranteed to arrive in order: a user.updated can overtake the user.created it follows. Write handlers as upserts keyed on the resource id so that either order ends in the same row. The dashboard keeps a log of each message and attempt, and a failed one can be replayed from there.

Catch a real Clerk webhook

1. Press Create webhook URL at the top of this page and copy the address.
2. In the Clerk Dashboard, select a development instance and open Webhooks.
3. Add an endpoint, paste the address as the URL, and subscribe to events such as user.created.
4. Open the endpoint's testing tab and send an example event, or sign up a test user in your development app.
5. Read the three svix- headers and the event body in the inbox above.

The endpoint's signing secret is shown on its page in the dashboard. Keep the webhook on a development instance while it points at a public inbox: the payloads contain names and email addresses.

To run a caught request against your own code, select it and press Open in API Tester: the method, headers and body are loaded into the request console, where you enter your server's public URL and send it. A body you edit will no longer match its signature — that is the signature doing its job.

Things that catch people out

• Decode the secret before using it. Keying the HMAC with the literal whsec_… string is the classic reason a hand-written check never matches.
• A webhook is not a sign-up hook. It arrives after the fact and possibly late; do not make the user's first page load depend on it having been processed.
• The same scheme, other senders. Several services deliver through Svix with identical headers, sometimes renamed to webhook-id, webhook-timestamp and webhook-signature.

api-tester.com is independent and is not affiliated with Clerk. Providers change header names, limits and retry schedules; treat the official Clerk documentation as the source of truth.

Related examples and tools

Other webhooks with a timestamp in the signature

• Stripe Webhook Example
• Slack Webhook Example
• HubSpot Webhook Example
• Mailgun Webhook Example
• Calendly Webhook Example

References

• Official Clerk documentation — The provider's own guide to the requests described on this page.
• Clerk Docs: sync Clerk data with webhooks — A worked endpoint, from setup to verification.
• Svix Docs: verifying webhooks manually — The signature scheme, for when you are not using the library.
• Standard Webhooks — The open specification this header and signature format follows.
• RFC 2104: HMAC — The keyed-hash construction this signature is built on.
• Node.js: crypto.timingSafeEqual() — The constant-time comparison used in the code on this page.

These links leave api-tester.com, which is independent of the companies and projects they point to.

Clerk webhook FAQ