clerk-webhooks-events
Configure Clerk webhooks and handle authentication events. Use when setting up user sync, handling auth events, or integrating Clerk with external systems. Trigger with phrases like "clerk webhooks", "clerk events", "clerk user sync", "clerk notifications", "clerk event handling".
- License 许可
- MIT
- 最近更新
- 2026-11-15
- Stars
- ★ 2.0k
- Forks
- 233
01 前言 Front Matter
- name
- clerk-webhooks-events
- author
- Jeremy Longshore <jeremy@intentsolutions.io>
- license
- MIT
- version
- 1.0.0
- description
- Configure Clerk webhooks and handle authentication events. Use when setting up user sync, handling auth events, or integrating Clerk with external systems. Trigger with phrases like "clerk webhooks", "clerk events", "clerk user sync", "clerk notifications", "clerk event handling".
- allowed-tools
- Read, Write, Edit, Bash(npm:*), Grep
03 SKILL.md 正文
Clerk Webhooks & Events
Overview
Configure and handle Clerk webhooks for user lifecycle events and data synchronization.
Prerequisites
- Clerk account with webhook access
- HTTPS endpoint for webhooks
- svix package for verification
Instructions
Step 1: Install Dependencies
npm install svix
Step 2: Create Webhook Endpoint
// app/api/webhooks/clerk/route.ts
import { Webhook } from 'svix'
import { headers } from 'next/headers'
import { WebhookEvent } from '@clerk/nextjs/server'
export async function POST(req: Request) {
const WEBHOOK_SECRET = process.env.CLERK_WEBHOOK_SECRET
if (!WEBHOOK_SECRET) {
throw new Error('CLERK_WEBHOOK_SECRET not set')
}
// Get Svix headers
const headerPayload = await headers()
const svix_id = headerPayload.get('svix-id')
const svix_timestamp = headerPayload.get('svix-timestamp')
const svix_signature = headerPayload.get('svix-signature')
if (!svix_id || !svix_timestamp || !svix_signature) {
return Response.json({ error: 'Missing headers' }, { status: 400 })
}
// Get body
const payload = await req.json()
const body = JSON.stringify(payload)
// Verify webhook
const wh = new Webhook(WEBHOOK_SECRET)
let evt: WebhookEvent
try {
evt = wh.verify(body, {
'svix-id': svix_id,
'svix-timestamp': svix_timestamp,
'svix-signature': svix_signature,
}) as WebhookEvent
} catch (err) {
console.error('Webhook verification failed:', err)
return Response.json({ error: 'Invalid signature' }, { status: 400 })
}
// Handle event
const eventType = evt.type
console.log(`Received webhook: ${eventType}`)
switch (eventType) {
case 'user.created':
await handleUserCreated(evt.data)
break
case 'user.updated':
await handleUserUpdated(evt.data)
break
case 'user.deleted':
await handleUserDeleted(evt.data)
break
case 'session.created':
await handleSessionCreated(evt.data)
break
case 'organization.created':
await handleOrgCreated(evt.data)
break
default:
console.log(`Unhandled event type: ${eventType}`)
}
return Response.json({ success: true })
}
Step 3: Implement Event Handlers
// lib/webhook-handlers.ts
import { db } from './db'
interface ClerkUserData {
id: string
email_addresses: Array<{ email_address: string; id: string }>
first_name: string | null
last_name: string | null
image_url: string
created_at: number
updated_at: number
}
export async function handleUserCreated(data: ClerkUserData) {
const primaryEmail = data.email_addresses.find(
e => e.id === data.primary_email_address_id
)?.email_address
await db.user.create({
data: {
clerkId: data.id,
email: primaryEmail,
firstName: data.first_name,
lastName: data.last_name,
imageUrl: data.image_url,
createdAt: new Date(data.created_at)
}
})
// Send welcome email
await sendWelcomeEmail(primaryEmail)
console.log(`User created: ${data.id}`)
}
export async function handleUserUpdated(data: ClerkUserData) {
const primaryEmail = data.email_addresses.find(
e => e.id === data.primary_email_address_id
)?.email_address
await db.user.update({
where: { clerkId: data.id },
data: {
email: primaryEmail,
firstName: data.first_name,
lastName: data.last_name,
imageUrl: data.image_url,
updatedAt: new Date(data.updated_at)
}
})
console.log(`User updated: ${data.id}`)
}
export async function handleUserDeleted(data: { id: string }) {
await db.user.delete({
where: { clerkId: data.id }
})
// Clean up user data
await cleanupUserData(data.id)
console.log(`User deleted: ${data.id}`)
}
export async function handleSessionCreated(data: any) {
// Log session for analytics
await db.sessionLog.create({
data: {
userId: data.user_id,
sessionId: data.id,
createdAt: new Date(data.created_at),
userAgent: data.user_agent
}
})
console.log(`Session created: ${data.id}`)
}
export async function handleOrgCreated(data: any) {
await db.organization.create({
data: {
clerkOrgId: data.id,
name: data.name,
slug: data.slug,
createdAt: new Date(data.created_at)
}
})
console.log(`Organization created: ${data.id}`)
}
Step 4: Idempotency and Error Handling
// lib/webhook-idempotency.ts
import { Redis } from '@upstash/redis'
const redis = Redis.fromEnv()
export async function processWithIdempotency(
eventId: string,
handler: () => Promise<void>
) {
const key = `webhook:${eventId}`
// Check if already processed
const processed = await redis.get(key)
if (processed) {
console.log(`Event ${eventId} already processed`)
return { skipped: true }
}
try {
await handler()
// Mark as processed (expire after 24 hours)
await redis.set(key, 'processed', { ex: 86400 })
return { success: true }
} catch (error) {
// Log error but don't mark as processed
console.error(`Failed to process ${eventId}:`, error)
throw error
}
}
// Usage in webhook handler
export async function POST(req: Request) {
// ... verification code ...
const svix_id = headerPayload.get('svix-id')!
const result = await processWithIdempotency(svix_id, async () => {
switch (evt.type) {
case 'user.created':
await handleUserCreated(evt.data)
break
// ... other handlers
}
})
return Response.json(result)
}
Step 5: Configure Webhook in Clerk Dashboard
- Go to Clerk Dashboard > Webhooks
- Add endpoint URL:
https://yourdomain.com/api/webhooks/clerk - Select events:
user.createduser.updateduser.deletedsession.createdsession.endedorganization.*(if using organizations)
- Copy webhook secret to environment
Available Events
| Event | Description |
|---|---|
user.created |
New user signed up |
user.updated |
User profile changed |
user.deleted |
User account deleted |
session.created |
New session started |
session.ended |
Session terminated |
session.revoked |
Session manually revoked |
organization.created |
Org created |
organization.updated |
Org settings changed |
organization.deleted |
Org deleted |
organizationMembership.* |
Member added/removed |
email.created |
Email verification sent |
Output
- Webhook endpoint configured
- Event handlers implemented
- Idempotency protection
- User data sync working
Testing Webhooks Locally
# Use ngrok for local testing
npx ngrok http 3000
# Or use Clerk CLI
npx @clerk/cli dev
# Test with curl
curl -X POST http://localhost:3000/api/webhooks/clerk \
-H "Content-Type: application/json" \
-H "svix-id: test" \
-H "svix-timestamp: $(date +%s)" \
-H "svix-signature: v1,..." \
-d '{"type":"user.created","data":{}}'
Error Handling
| Error | Cause | Solution |
|---|---|---|
| Invalid signature | Wrong secret | Verify CLERK_WEBHOOK_SECRET |
| Missing headers | Request not from Clerk | Check sender is Clerk |
| Duplicate processing | Event sent twice | Implement idempotency |
| Timeout | Handler too slow | Use background jobs |
Resources
Next Steps
Proceed to clerk-performance-tuning for optimization strategies.
04 同仓库更多 Skills
theme-factory
Toolkit for styling artifacts with a theme. These artifacts can be slides, docs, reportings, HTML landing pages, etc. There are 10 pre-set themes with colors/fonts that you can apply to any artifact that has been creating, or can generate a new theme on-the-fly.
web-artifacts-builder
Suite of tools for creating elaborate, multi-component claude.ai HTML artifacts using modern frontend web technologies (React, Tailwind CSS, shadcn/ui). Use for complex artifacts requiring state management, routing, or shadcn/ui components - not for simple single-file HTML/JSX artifacts.
webapp-testing
Toolkit for interacting with and testing local web applications using Playwright. Supports verifying frontend functionality, debugging UI behavior, capturing browser screenshots, and viewing browser logs.
neuropixels-analysis
Neuropixels neural recording analysis. Load SpikeGLX/OpenEphys data, preprocess, motion correction, Kilosort4 spike sorting, quality metrics, Allen/IBL curation, AI-assisted visual analysis, for Neuropixels 1.0/2.0 extracellular electrophysiology. Use when working with neural recordings, spike sorting, extracellular electrophysiology, or when the user mentions Neuropixels, SpikeGLX, Open Ephys, Kilosort, quality metrics, or unit curation.
skill-creator
Guide for creating effective skills. This skill should be used when users want to create a new skill (or update an existing skill) that extends Claude's capabilities with specialized knowledge, workflows, or tool integrations.
notebooklm
Use this skill to query your Google NotebookLM notebooks directly from Claude Code for source-grounded, citation-backed answers from Gemini. Browser automation, library management, persistent auth. Drastically reduced hallucinations through document-only responses.