在 Clerk 应用中用 Webhooks…

当你需要在 Clerk 应用中通过 webhook 异步同步用户、会话、组织、订阅、支付等事件到数据库或触发通知/集成时。

适用场景

解决思路

1. 在每个 webhook handler 中调用 verifyWebhook(req) 验证签名，不要跳过，即使处理器只发送通知。
2. 根据框架从对应包导入 verifyWebhook：Next.js 用 @clerk/nextjs/webhooks，Express 用 @clerk/express/webhooks，Astro 用 @clerk/astro/webhooks，Fastify 用 @clerk/fastify/webhooks 等；它自动读取 CLERK_WEBHOOK_SIGNING_SECRET，签名错误会抛错。
3. 在 Clerk middleware 中把 webhook 路由设为公开：在 proxy.ts（Next.js <=15 为 middleware.ts）用 createRouteMatcher(['/api/webhooks(.*)']) 匹配公开路由，并在 clerkMiddleware 中仅对非公开路由调用 auth.protect()，否则 Clerk 返回 401。
4. 在 Next.js App Router 的 app/api/webhooks/route.ts 中创建 POST handler：用 try/catch 包裹 verifyWebhook(req)，验证失败时 console.error 并返回 new Response('Verification failed', { status: 400 })。
5. 处理 user.created：从 evt.data 解构 id、email_addresses、first_name、last_name，取 email_addresses[0]?.email_address 作为 email，拼接 name，然后 await db.users.create({ data: { clerkId: id, email, name } })。
6. 处理 user.updated：从 evt.data 解构 id、email_addresses、first_name、last_name，取主邮箱，然后 await db.users.update({ where: { clerkId: id }, data: { email, first_name, last_name } })。
7. 处理 user.deleted：从 evt.data 解构 id，然后 await db.users.delete({ where: { clerkId: id } })。
8. 处理 organizationMembership.created：从 evt.data 解构 organization、public_user_data、role，取 organization.id 和 public_user_data.user_id，然后 await db.teamMembers.create({ data: { orgId, userId, role } })。
9. 处理 organizationMembership.deleted：从 evt.data 解构 organization、public_user_data，取 organization.id 和 public_user_data.user_id，然后 await db.teamMembers.delete({ where: { orgId_userId: { orgId, userId } } })。
10. handler 成功处理后返回 new Response('OK', { status: 200 }) 以确认接收。
11. 通知类 handler 同样先验证签名；监听 user.created 后从 evt.data 提取 email 和 name，调用 Resend 的 resend.emails.send 发送欢迎邮件，再向 SLACK_WEBHOOK_URL 发 POST JSON 通知，最后返回 200。
12. 组织成员同步完整示例：处理 organization.created 时用 evt.data 的 id、name 创建 db.workspaces；处理 organizationMembership.created 时创建 team_members 和 workspaces；处理 organizationMembership.deleted 时删除 team_members 和 workspaces。
13. 其他框架（Express、Astro、Fastify、Nuxt、React Router、TanStack Start）使用各 Clerk SDK 自带的框架特定 verifyWebhook 适配器；完整示例见 references/frameworks.md。
14. 用 evt.type 作为判别联合收窄 evt.data 类型，例如 if (evt.type === 'user.created') 后 evt.data 为 UserJSON 并可自动补全 id、email_addresses 等。
15. 需要手动类型嵌套 payload 时，从框架 webhook 子路径导入 DeletedObjectJSON、EmailJSON、OrganizationInvitationJSON、OrganizationJSON、OrganizationMembershipJSON、SessionJSON、SMSMessageJSON、UserJSON。
16. 按事件类型解构 evt.data：用户事件取 id、email_addresses（[0].email_address 为主邮箱）、first_name、last_name、image_url、public_metadata；组织事件取 id、name、slug；组织成员事件取 organization、public_user_data、role（如 org:admin、org:member）。
17. 可监听的事件目录：User 为 user.created/user.updated/user.deleted；Session 为 session.created/session.ended/session.removed/session.revoked；Organization 为 organization.created/organization.updated/organization.deleted；Organization Membership 为 organizationMembership.created/organizationMembership.updated/organizationMembership.deleted；Organization Domain 为 organizationDomain.created/organizationDomain.updated/organizationDomain.deleted；Organization Invitation 为 organizationInvitation.accepted/organizationInvitation.created/organizationInvitation.revoked；Communication 为 email.created/sms.created；Waitlist 为 waitlistEntry.created/waitlistEntry.updated；Permission 为 permission.created/permission.updated/permission.deleted；Role 为 role.created/role.updated/role.deleted；Subscription 为 subscription.created/subscription.updated/subscription.active/subscription.pastDue；Subscription Item 为 subscriptionItem.created/subscriptionItem.active/subscriptionItem.updated/subscriptionItem.canceled/subscriptionItem.upcoming/subscriptionItem.ended/subscriptionItem.abandoned/subscriptionItem.incomplete/subscriptionItem.pastDue/subscriptionItem.freeTrialEnding；Payment 为 paymentAttempt.created/paymentAttempt.updated。
18. 处理可靠性：返回 2xx 表示成功，4xx/5xx 会触发 Svix 按固定时间表重试；用 svix-id header 作为幂等键去重重试事件；失败 webhook 可从 Dashboard 重放。
19. 常见陷阱修复：Next.js 验证失败时使用 @clerk/nextjs/webhooks 并直接传入 req；Express 验证失败时对 webhook 路由使用 express.raw({ type: 'application/json' })；404 时使用 /api/webhooks 或保留已有路径；401 时在 clerkMiddleware() 中把路由设为公开；DB 无数据时等待或查看日志；重复条目时同时处理 user.updated；超时时把异步工作放入队列并先返回 200。
20. 本地测试用 Clerk CLI 的 first-party tunnel：运行 clerk webhooks listen --token "$(clerk webhooks token)" --forward-to http://localhost:3000/api/webhooks，并把打印的 relay URL（https://webhooks.clerk.com/in/c_.../）添加为 Dashboard webhook endpoint；否则事件不会流动；svix-* headers 会保留，因此 verifyWebhook() 可正常使用。
21. 查看 clerk-cli skill 了解 flags、离线签名检查（clerk webhooks verify）和 agent-mode 行为；若不用 CLI，则自行用 ngrok、localtunnel 或 Cloudflare Tunnel 隧道 localhost:3000，并把公共 URL 加入 Dashboard endpoint。
22. 生产部署时更新 webhook endpoint URL 为生产域名，并把 CLERK_WEBHOOK_SIGNING_SECRET 复制到生产环境变量。
23. 需要框架级完整 handler 示例时参考 references/frameworks.md；相关能力参见 clerk-cli、clerk-setup、clerk-orgs、clerk-billing、clerk-backend-api 技能。
24. 不要依赖 webhook 投递作为同步流程的一部分；对于用户刚创建、session token 可携带的数据，从 Clerk session token 读取或直接调用 Backend API，webhook 只填补其他用户或 session token 不携带的事件数据。

适用边界 · 注意事项

• 需要强一致、同步等待用户刚创建数据的 onboarding 流程不适用；应从 Clerk session token 读取或直接调用 Backend API。
• 未使用 Clerk 或没有 CLERK_WEBHOOK_SIGNING_SECRET（Clerk Dashboard 的 Svix signing secret）的环境不适用。
• 无法接受异步最终一致、重试和幂等设计，或不能把 webhook 路由公开的环境不适用。