Loading...
Loading...
Receive and verify Clerk webhooks. Use when setting up Clerk webhook handlers, debugging signature verification, or handling user events like user.created, user.updated, session.created, or organization.created.
npx skill4agent add hookdeck/webhook-skills clerk-webhookssvix-*standardwebhooksconst express = require('express');
const { Webhook } = require('standardwebhooks');
const app = express();
// CRITICAL: Use express.raw() for webhook endpoint - verification needs raw body
app.post('/webhooks/clerk',
express.raw({ type: 'application/json' }),
async (req, res) => {
const secret = process.env.CLERK_WEBHOOK_SECRET || process.env.CLERK_WEBHOOK_SIGNING_SECRET;
if (!secret || !secret.startsWith('whsec_')) {
return res.status(500).json({ error: 'Server configuration error' });
}
const svixId = req.headers['svix-id'];
const svixTimestamp = req.headers['svix-timestamp'];
const svixSignature = req.headers['svix-signature'];
if (!svixId || !svixTimestamp || !svixSignature) {
return res.status(400).json({ error: 'Missing required webhook headers' });
}
// standardwebhooks expects webhook-* header names; Clerk sends svix-* (same protocol)
const headers = {
'webhook-id': svixId,
'webhook-timestamp': svixTimestamp,
'webhook-signature': svixSignature
};
try {
const wh = new Webhook(secret);
const event = wh.verify(req.body, headers);
if (!event) return res.status(400).json({ error: 'Invalid payload' });
switch (event.type) {
case 'user.created': console.log('User created:', event.data.id); break;
case 'user.updated': console.log('User updated:', event.data.id); break;
case 'session.created': console.log('Session created:', event.data.user_id); break;
case 'organization.created': console.log('Organization created:', event.data.id); break;
default: console.log('Unhandled:', event.type);
}
res.status(200).json({ success: true });
} catch (err) {
res.status(400).json({ error: err.name === 'WebhookVerificationError' ? err.message : 'Webhook verification failed' });
}
}
);import os
import hmac
import hashlib
import base64
from fastapi import FastAPI, Request, HTTPException
from time import time
webhook_secret = os.environ.get("CLERK_WEBHOOK_SECRET")
@app.post("/webhooks/clerk")
async def clerk_webhook(request: Request):
# Get Svix headers
svix_id = request.headers.get("svix-id")
svix_timestamp = request.headers.get("svix-timestamp")
svix_signature = request.headers.get("svix-signature")
if not all([svix_id, svix_timestamp, svix_signature]):
raise HTTPException(status_code=400, detail="Missing required Svix headers")
# Get raw body
body = await request.body()
# Manual signature verification
signed_content = f"{svix_id}.{svix_timestamp}.{body.decode()}"
# Extract base64 secret after 'whsec_' prefix
secret_bytes = base64.b64decode(webhook_secret.split('_')[1])
expected_signature = base64.b64encode(
hmac.new(secret_bytes, signed_content.encode(), hashlib.sha256).digest()
).decode()
# Svix can send multiple signatures, check each one
signatures = [sig.split(',')[1] for sig in svix_signature.split(' ')]
if expected_signature not in signatures:
raise HTTPException(status_code=400, detail="Invalid signature")
# Check timestamp (5-minute window)
current_time = int(time())
if current_time - int(svix_timestamp) > 300:
raise HTTPException(status_code=400, detail="Timestamp too old")
# Handle event...
return {"success": True}For complete working examples with tests, see:
- examples/express/ - Full Express implementation
- examples/nextjs/ - Next.js App Router implementation
- examples/fastapi/ - Python FastAPI implementation
| Event | Description |
|---|---|
| New user account created |
| User profile or metadata updated |
| User account deleted |
| User signed in |
| User signed out |
| Session revoked |
| New organization created |
| Organization settings updated |
| User added to organization |
| Invite sent to join organization |
For full event reference, see Clerk Webhook Events and Dashboard → Webhooks → Event Catalog.
# Official name (used by @clerk/nextjs and Clerk docs)
CLERK_WEBHOOK_SIGNING_SECRET=whsec_xxxxx
# Alternative name (used in this skill's examples)
CLERK_WEBHOOK_SECRET=whsec_xxxxx# Install Hookdeck CLI for local webhook testing
brew install hookdeck/hookdeck/hookdeck
# Start tunnel (no account needed)
hookdeck listen 3000 --path /webhooks/clerk// Generated with: clerk-webhooks skill
// https://github.com/hookdeck/webhook-skills