用途:在应用中接收 Clerk 的实时事件,把用户、组织等变化同步到自有数据库或触发通知、发信等后续动作。
主要能力:覆盖用户创建、更新、删除,组织创建、成员加入与移除等事件;给出 Next.js App Router 与 Express 两种完整处理器写法;所有处理器都强调必须用 verifyWebhook(req) 校验签名,并自动读取 CLERK_WEBHOOK_SECRET;Next.js 中 Webhook 路由必须通过 clerkMiddleware 的 createRouteMatcher 设为公开,否则返回 401;Express 中必须对本路由使用 express.raw({ type: 'application/json' }),不能用 express.json(),否则原始字节被解析会导致校验失败;签名校验失败返回 400,成功返回 200;提供事件类型清单及 user、organization、organizationMembership 等载荷字段说明;说明 Svix 重试机制,建议用 svix-id 作为幂等键,并提醒处理 user.updated 以免重复条目,慢任务先返回 200 再异步处理。
使用方式:在 app/api/webhooks/route.ts 编写 POST 处理器,校验后按 evt.type 分支处理 evt.data;本地可用 ngrok 暴露 localhost:3000 并在 Dashboard 配置端点,生产环境更新端点 URL 并将 CLERK_WEBHOOK_SECRET 配入生产环境变量。
限制:资料未提供官方定价与具体价格、未给出完整事件目录之外更多细节、未提供非 Next.js/Express 框架的示例;部分示例中的数据库客户端(如 @/lib/db)与邮件、Slack 配置需用户自行准备。