Clerk Webhooks 完整指南：Next.js 用户认证事件实时同步与集成

clerk-webhooks by clerk/skills

2,500 周安装量

30 GitHub Stars

GitHub

安装命令

npx skills add https://github.com/clerk/skills --skill clerk-webhooks

开发云服务

🇨🇳中文介绍

Webhooks

前提条件：Webhooks 是异步的。请将其用于后台任务（同步、通知），而非同步流程。

文档参考

任务	链接
概述	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 (事件目录标签页)

快速开始

在 app/api/webhooks/route.ts 创建端点
使用 @clerk/nextjs/webhooks 中的

广告位招租

在这里展示您的产品或服务

触达数万 AI 开发者，精准高效

联系我们

将路由设为公开

Webhooks 请求是未签名的。路由必须是公开的：

确保 clerkMiddleware() 不保护 /api/webhooks(.*) 路径。

使用正确的导入和单个参数：

import { verifyWebhook } from '@clerk/nextjs/webhooks'
const evt = await verifyWebhook(req)  // 直接传递请求对象

类型安全的事件

缩小到特定事件：

if (evt.type === 'user.created') {
  // TypeScript 知道 evt.data 的结构
}

处理所有三种事件

不要只监听 user.created。同时处理 user.updated 和 user.deleted。

立即返回 200，将长时间操作加入队列：

await queue.enqueue('process-webhook', evt)
return new Response('Received', { status: 200 })

重试：Svix 会对失败的 webhooks 重试长达 3 天。返回 2xx 表示成功，返回 4xx/5xx 会触发重试。

重放：可以从仪表板重放失败的 webhooks。

症状	原因	修复方法
验证失败	导入或使用方式错误	使用 `@clerk/nextjs/webhooks`，直接传递 `req`
路由未找到 (404)	路径错误	使用 `/api/webhooks`
未授权 (401)	路由受保护	将路由设为公开
数据库中没有数据	异步作业挂起	等待/检查日志
重复条目	仅处理了 `user.created`	同时处理 `user.updated`
超时	处理程序太慢	将异步工作加入队列

本地：使用 ngrok 将 localhost:3000 隧道到互联网。将 ngrok URL 添加到仪表板端点。

生产环境：将 webhook 端点 URL 更新为生产域名。将签名密钥复制到生产环境变量中。

🇺🇸English

Webhooks

Prerequisite : Webhooks are asynchronous. Use for background tasks (sync, notifications), not synchronous flows.

Documentation Reference

Task	Link
Overview	https://clerk.com/docs/guides/development/webhooks/overview
Sync to database	https://clerk.com/docs/guides/development/webhooks/syncing
Debugging	https://clerk.com/docs/guides/development/webhooks/debugging
Event catalog	https://dashboard.clerk.com/~/webhooks (Event Catalog tab)

Quick Start

Create endpoint at app/api/webhooks/route.ts
Use verifyWebhook(req) from @clerk/nextjs/webhooks
Dashboard → Webhooks → Add Endpoint
Set CLERK_WEBHOOK_SIGNING_SECRET in env
Make route public (not protected by middleware)

Supported Events

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

Full catalog: Dashboard → Webhooks → Event Catalog

When to Sync

Do sync when:

Need other users' data (social features, profiles)
Storing extra custom fields (birthday, country, bio)
Building notifications or integrations

Don't sync when:

Only need current user data (use session token)
No custom fields (Clerk has everything)
Need immediate access (webhooks are eventual consistency)

Key Patterns

Make Route Public

Webhooks come unsigned. Route must be public:

Ensure clerkMiddleware() doesn't protect /api/webhooks(.*) path.

Verify Webhook

Use correct import and single parameter:

import { verifyWebhook } from '@clerk/nextjs/webhooks'
const evt = await verifyWebhook(req)  // Pass request directly

Type-Safe Events

Narrow to specific event:

if (evt.type === 'user.created') {
  // TypeScript knows evt.data structure
}

Handle All Three Events

Don't only listen to user.created. Also handle user.updated and user.deleted.

Queue Async Work

Return 200 immediately, queue long operations:

await queue.enqueue('process-webhook', evt)
return new Response('Received', { status: 200 })

Webhook Reliability

Retries : Svix retries failed webhooks for up to 3 days. Return 2xx to succeed, 4xx/5xx to retry.

Replay : Failed webhooks can be replayed from Dashboard.

Common Pitfalls

Symptom	Cause	Fix
Verification fails	Wrong import or usage	Use `@clerk/nextjs/webhooks`, pass `req` directly
Route not found (404)	Wrong path	Use `/api/webhooks`
Not authorized (401)	Route is protected	Make route public
No data in DB	Async job pending	Wait/check logs
Duplicate entries	Only handling `user.created`	Also handle `user.updated`

Testing & Deployment

Local : Use ngrok to tunnel localhost:3000 to internet. Add ngrok URL to Dashboard endpoint.

Production : Update webhook endpoint URL to production domain. Copy signing secret to production env vars.

Weekly Installs

1.8K

Repository

clerk/skills

GitHub Stars

First Seen

Jan 30, 2026

Security Audits

Gen Agent Trust HubPass SocketPass SnykPass

Installed on

codex1.6K

opencode1.5K

github-copilot1.5K

gemini-cli1.5K

amp1.4K

kimi-cli1.4K

Clerk Webhooks 完整指南：Next.js 用户认证事件实时同步与集成

🇨🇳中文介绍

Webhooks

文档参考

快速开始

相关 Skills

支持的事件

何时进行同步

关键模式

将路由设为公开

验证 Webhook

类型安全的事件

处理所有三种事件

异步工作入队

Webhook 可靠性

常见问题

测试与部署

🇺🇸English

Webhooks

Documentation Reference

Quick Start

Supported Events

When to Sync

Key Patterns

Make Route Public

Verify Webhook

Type-Safe Events

Handle All Three Events

Queue Async Work

Webhook Reliability

Common Pitfalls

Testing & Deployment