clerk-webhooks

Name: clerk-webhooks
Author: hookdeck

80stars10forks

How to install clerk-webhooks?

hookdeck/webhook-skills/clerk-webhooks

$npx -y skills add hookdeck/webhook-skills --skill clerk-webhooks

Installs into the current project.

Summary

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.

Files · 1

View on GitHub

SKILL.md

1	# Clerk Webhooks
2
3	## When to Use This Skill
4
5	- Setting up Clerk webhook handlers
6	- Debugging signature verification failures
7	- Understanding Clerk event types and payloads
8	- Handling user, session, or organization events
9
10	## Essential Code (USE THIS)
11
12	### Express Webhook Handler
13
14	Clerk uses the [Standard Webhooks](https://www.standardwebhooks.com/) protocol (Clerk sends `svix-*` headers; same format). Use the `standardwebhooks` npm package:
15
16	```javascript
17	const express = require('express');
18	const { Webhook } = require('standardwebhooks');
19
20	const app = express();
21
22	// CRITICAL: Use express.raw() for webhook endpoint - verification needs raw body
23	app.post('/webhooks/clerk',
24	express.raw({ type: 'application/json' }),
25	async (req, res) => {
26	const secret = process.env.CLERK_WEBHOOK_SECRET \|\| process.env.CLERK_WEBHOOK_SIGNING_SECRET;
27	if (!secret \|\| !secret.startsWith('whsec_')) {
28	return res.status(500).json({ error: 'Server configuration error' });
29	}
30	const svixId = req.headers['svix-id'];
31	const svixTimestamp = req.headers['svix-timestamp'];
32	const svixSignature = req.headers['svix-signature'];
33	if (!svixId \|\| !svixTimestamp \|\| !svixSignature) {
34	return res.status(400).json({ error: 'Missing required webhook headers' });
35	}
36	// standardwebhooks expects webhook-* header names; Clerk sends svix-* (same protocol)
37	const headers = {
38	'webhook-id': svixId,
39	'webhook-timestamp': svixTimestamp,
40	'webhook-signature': svixSignature
41	};
42	try {
43	const wh = new Webhook(secret);
44	const event = wh.verify(req.body, headers);
45	if (!event) return res.status(400).json({ error: 'Invalid payload' });
46	switch (event.type) {
47	case 'user.created': console.log('User created:', event.data.id); break;
48	case 'user.updated': console.log('User updated:', event.data.id); break;
49	case 'session.created': console.log('Session created:', event.data.user_id); break;
50	case 'organization.created': console.log('Organization created:', event.data.id); break;
51	default: console.log('Unhandled:', event.type);
52	}
53	res.status(200).json({ success: true });
54	} catch (err) {
55	res.status(400).json({ error: err.name === 'WebhookVerificationError' ? err.message : 'Webhook verification failed' });
56	}
57	}
58	);
59	```
60
61	### Python (FastAPI) Webhook Handler
62
63	```python
64	import os
65	import hmac
66	import hashlib
67	import base64
68	from fastapi import FastAPI, Request, HTTPException
69	from time import time
70
71	webhook_secret = os.environ.get("CLERK_WEBHOOK_SECRET")
72
73	@app.post("/webhooks/clerk")
74	async def clerk_webhook(request: Request):
75	# Get Svix headers
76	svix_id = request.headers.get("svix-id")
77	svix_timestamp = request.headers.get("svix-timestamp")
78	svix_signature = request.headers.get("svix-signature")
79
80	if not all([svix_id, svix_timestamp, svix_signature]):
81	raise HTTPException(status_code=400, detail="Missing required Svix headers")
82
83	# Get raw body
84	body = await request.body()
85
86	# Manual signature verification
87	signed_content = f"{svix_id}.{svix_timestamp}.{body.decode()}"
88
89	# Extract base64 secret after 'whsec_' prefix
90	secret_bytes = base64.b64decode(webhook_secret.split('_')[1])
91	expected_signature = base64.b64encode(
92	hmac.new(secret_bytes, signed_content.encode(), hashlib.sha256).digest()
93	).decode()
94
95	# Svix can send multiple signatures, check each one
96	signatures = [sig.split(',')[1] for sig in svix_signature.split(' ')]
97	if expected_signature not in signatures:
98	raise HTTPException(status_code=400, detail="Invalid signature")
99
100	# Check timestamp (5-minute window)
101	current_time = int(time())
102	if current_time - int(svix_timestamp) > 300:
103	raise HTTPException(status_code=400, detail="Timestamp too old")
104
105	# Handle event...
106	return {"success": True}
107	```
108
109	> For complete working examples with tests, see:
110	> - [examples/express/](examples/express/) - Full Express implementation
111	> - [examples/nextjs/](examples/nextjs/) - Next.js App Router implementation
112	> - [examples/fastapi/](examples/fastapi/) - Python FastAPI implementation
113
114	## Common Event Types
115
116	\| Event \| Description \|
117	\|-------\|-------------\|
118	\| `user.created` \| New user account created \|
119	\| `user.updated` \| User profile or metadata updated \|
120	\| `user.deleted` \| User account deleted \|
121	\| `session.created` \| User signed in \|
122	\| `session.ended` \| User signed out \|
123	\| `session.removed` \| Session revoked \|
124	\| `organization.created` \| New organization created \|
125	\| `organization.updated` \| Organization settings updated \|
126	\| `organizat

People who liked this also viewed

6 picks

Type

clerk-webhooks

80stars10forks

View on GitHub

How to install clerk-webhooks?

hookdeck/webhook-skills/clerk-webhooks

$npx -y skills add hookdeck/webhook-skills --skill clerk-webhooks

Installs into the current project.

Summary

Files · 1

View on GitHub

SKILL.md

1	# Clerk Webhooks
2
3	## When to Use This Skill
4
5	- Setting up Clerk webhook handlers
6	- Debugging signature verification failures
7	- Understanding Clerk event types and payloads
8	- Handling user, session, or organization events
9
10	## Essential Code (USE THIS)
11
12	### Express Webhook Handler
13
14	Clerk uses the [Standard Webhooks](https://www.standardwebhooks.com/) protocol (Clerk sends `svix-*` headers; same format). Use the `standardwebhooks` npm package:
15
16	```javascript
17	const express = require('express');
18	const { Webhook } = require('standardwebhooks');
19
20	const app = express();
21
22	// CRITICAL: Use express.raw() for webhook endpoint - verification needs raw body
23	app.post('/webhooks/clerk',
24	express.raw({ type: 'application/json' }),
25	async (req, res) => {
26	const secret = process.env.CLERK_WEBHOOK_SECRET \|\| process.env.CLERK_WEBHOOK_SIGNING_SECRET;
27	if (!secret \|\| !secret.startsWith('whsec_')) {
28	return res.status(500).json({ error: 'Server configuration error' });
29	}
30	const svixId = req.headers['svix-id'];
31	const svixTimestamp = req.headers['svix-timestamp'];
32	const svixSignature = req.headers['svix-signature'];
33	if (!svixId \|\| !svixTimestamp \|\| !svixSignature) {
34	return res.status(400).json({ error: 'Missing required webhook headers' });
35	}
36	// standardwebhooks expects webhook-* header names; Clerk sends svix-* (same protocol)
37	const headers = {
38	'webhook-id': svixId,
39	'webhook-timestamp': svixTimestamp,
40	'webhook-signature': svixSignature
41	};
42	try {
43	const wh = new Webhook(secret);
44	const event = wh.verify(req.body, headers);
45	if (!event) return res.status(400).json({ error: 'Invalid payload' });
46	switch (event.type) {
47	case 'user.created': console.log('User created:', event.data.id); break;
48	case 'user.updated': console.log('User updated:', event.data.id); break;
49	case 'session.created': console.log('Session created:', event.data.user_id); break;
50	case 'organization.created': console.log('Organization created:', event.data.id); break;
51	default: console.log('Unhandled:', event.type);
52	}
53	res.status(200).json({ success: true });
54	} catch (err) {
55	res.status(400).json({ error: err.name === 'WebhookVerificationError' ? err.message : 'Webhook verification failed' });
56	}
57	}
58	);
59	```
60
61	### Python (FastAPI) Webhook Handler
62
63	```python
64	import os
65	import hmac
66	import hashlib
67	import base64
68	from fastapi import FastAPI, Request, HTTPException
69	from time import time
70
71	webhook_secret = os.environ.get("CLERK_WEBHOOK_SECRET")
72
73	@app.post("/webhooks/clerk")
74	async def clerk_webhook(request: Request):
75	# Get Svix headers
76	svix_id = request.headers.get("svix-id")
77	svix_timestamp = request.headers.get("svix-timestamp")
78	svix_signature = request.headers.get("svix-signature")
79
80	if not all([svix_id, svix_timestamp, svix_signature]):
81	raise HTTPException(status_code=400, detail="Missing required Svix headers")
82
83	# Get raw body
84	body = await request.body()
85
86	# Manual signature verification
87	signed_content = f"{svix_id}.{svix_timestamp}.{body.decode()}"
88
89	# Extract base64 secret after 'whsec_' prefix
90	secret_bytes = base64.b64decode(webhook_secret.split('_')[1])
91	expected_signature = base64.b64encode(
92	hmac.new(secret_bytes, signed_content.encode(), hashlib.sha256).digest()
93	).decode()
94
95	# Svix can send multiple signatures, check each one
96	signatures = [sig.split(',')[1] for sig in svix_signature.split(' ')]
97	if expected_signature not in signatures:
98	raise HTTPException(status_code=400, detail="Invalid signature")
99
100	# Check timestamp (5-minute window)
101	current_time = int(time())
102	if current_time - int(svix_timestamp) > 300:
103	raise HTTPException(status_code=400, detail="Timestamp too old")
104
105	# Handle event...
106	return {"success": True}
107	```
108
109	> For complete working examples with tests, see:
110	> - [examples/express/](examples/express/) - Full Express implementation
111	> - [examples/nextjs/](examples/nextjs/) - Next.js App Router implementation
112	> - [examples/fastapi/](examples/fastapi/) - Python FastAPI implementation
113
114	## Common Event Types
115
116	\| Event \| Description \|
117	\|-------\|-------------\|
118	\| `user.created` \| New user account created \|
119	\| `user.updated` \| User profile or metadata updated \|
120	\| `user.deleted` \| User account deleted \|
121	\| `session.created` \| User signed in \|
122	\| `session.ended` \| User signed out \|
123	\| `session.removed` \| Session revoked \|
124	\| `organization.created` \| New organization created \|
125	\| `organization.updated` \| Organization settings updated \|
126	\| `organizat

People who liked this also viewed

6 picks

Type