用途
clerk-webhooks 用于接入 Clerk 的 Webhook 能力，实时接收 Clerk 产生的事件并做数据同步。资料明确说明 Webhook 是异步的，适用于后台任务（同步、通知），不适合同步流程。
主要能力
可监听的事件类别包括：
- User：user.created、user.updated、user.deleted
- Organization：organization.created、organization.updated、organization.deleted
- Organization Domain：organizationDomain.created、organizationDomain.updated、organizationDomain.deleted
- Organization Invitation：organizationInvitation.created、organizationInvitation.accepted、organizationInvitation.revoked
- Organization Membership：organizationMembership.created、organizationMembership.updated、organizationMembership.deleted
- Roles：role.created、role.updated、role.deleted
- Permissions：permission.created、permission.updated、permission.deleted
- Session：session.created、session.updated、session.ended、session.removed、session.revoked、session.pending
- Communication：email.created、sms.created
- Invitations：invitation.created、invitation.accepted、invitation.revoked
- Waitlist：waitlistEntry.created、waitlistEntry.updated
完整事件目录位于 Dashboard → Webhooks → Event Catalog。
使用方式
快速开始步骤：
- 在 app/api/webhooks/route.ts 创建端点
- 使用 @clerk/nextjs/webhooks 中的 verifyWebhook(req)
- Dashboard → Webhooks → Add Endpoint
- 设置环境变量 CLERK_WEBHOOK_SIGNING_SECRET
- 将路由设为公开（不被中间件保护）
关键模式：
- 公开路由：Webhook 无签名传入，需确保 clerkMiddleware() 不保护 /api/webhooks(.*) 路径。
- 校验 Webhook：使用正确导入与单一参数——
import { verifyWebhook } from '@clerk/nextjs/webhooks'
const evt = await verifyWebhook(req) // Pass request directly
- 类型安全事件：按事件类型收窄——
if (evt.type === 'user.created') {
// TypeScript knows evt.data structure
}
- 处理全部三类事件：不要只监听 user.created，也要处理 user.updated 和 user.deleted。
- 异步工作入队：立即返回 200，将耗时操作入队——
await queue.enqueue('process-webhook', evt)
return new Response('Received', { status: 200 })
适用场景
需要同步的情况：
- 需要其他用户的数据（社交功能、个人资料）
- 存储额外的自定义字段（生日、国家、简介）
- 构建通知或集成
不需要同步的情况：
- 只需要当前用户数据（使用 session token）
- 没有自定义字段（Clerk 已包含所有信息）
- 需要立即访问（Webhook 是最终一致性）
可靠性与限制
- 重试：Svix 会对失败的 Webhook 最多重试 3 天。返回 2xx 表示成功，4xx/5xx 触发重试。
- 重放：失败的 Webhook 可从 Dashboard 重放。
- 文档参考：
- 概览：https://clerk.com/docs/guides/development/webhooks/overview
- 同步到数据库：https://clerk.com/docs/guides/development/webhooks/syncing
- 调试：https://clerk.com/docs/guides/development/webhooks/debugging
- 事件目录：https://dashboard.clerk.com/~/webhooks（Event Catalog 标签页）
常见陷阱：
| 症状 | 原因 | 修复 |
|---|---|---|
| 校验失败 | 导入或用法错误 | 使用 @clerk/nextjs/webhooks，直接传入 req |
| 路由未找到（404） | 路径错误 | 使用 /api/webhooks |
| 未授权（401） | 路由被保护 | 将路由设为公开 |
| 数据库无数据 | 异步任务待处理 | 等待/检查日志 |
| 重复条目 | 只处理 user.created | 同时处理 user.updated |
| 超时 | 处理程序过慢 | 将异步工作入队 |
测试与部署：
- 本地：使用 ngrok 将 localhost:3000 隧道到公网，将 ngrok URL 添加到 Dashboard 端点。
- 生产：将 Webhook 端点 URL 更新为生产域名，将签名密钥复制到生产环境变量。
关于收费、价格与平台支持等具体信息，资料中暂未提供。