把身份事件推出去：Casdoor Webhook 事件系统 5 步上手指南-平芜编程栈

把身份事件推出去：Casdoor Webhook 事件系统 5 步上手指南

【免费下载链接】casdoorAn open-source Agent-first Identity and Access Management (IAM) /LLM MCP & agent gateway and auth server with web UI supporting OpenClaw, MCP, OAuth, OIDC, SAML, CAS, LDAP, SCIM, WebAuthn, TOTP, MFA, Face ID, Google Workspace, Azure AD项目地址: https://gitcode.com/gh_mirrors/ca/casdoor

📮 Casdoor Webhook（Webhook 事件系统）是 Casdoor 内置的身份事件推送机制：每当登录、注册、用户创建等事件发生时，Casdoor 会按你的配置把事件数据以 HTTP 请求的形式推送到你指定的自定义回调地址，并自带失败重试、事件重放、投递状态追踪三大能力，帮你把 IAM 数据实时同步到 CRM、审批流或数据仓库。

一、Casdoor Webhook 是什么？能解决什么问题？

想象一下：员工在 Casdoor 登录成功的那一刻，你的 HR 系统就想同步这条记录；新用户注册完成，你就想自动开通内部权限。传统做法是定时轮询数据库，而Casdoor Webhook让你反过来"把身份事件推出去"——事件发生时，Casdoor 主动调用你的回调接口。

它有三个突出特点：

✅异步解耦：事件先落库成 Webhook 事件，后台 Worker 负责投递，不影响登录主流程
✅自动重试：支持固定间隔或指数退避重试，默认最多 3 次
✅可观测可重放：每次投递的状态、响应码、报错都留痕，失败事件可一键重放

核心源码分布：

Webhook 配置模型：object/webhook.go
事件模型与状态机：object/webhook_event.go
投递 Worker 与重试逻辑：object/webhook_worker.go
事件发送（HTTP 请求构造）：object/webhook_util.go

二、一个 Webhook 事件的完整生命周期 🔁

这是理解整个系统的关键。一次"登录成功"事件的流转如下：

1️⃣ 触发：Casdoor 产生一条记录（Record），object/record.go 中的SendWebhooks会筛选出所有匹配该组织和该事件类型的 Webhook 配置。

2️⃣ 落库：为每个匹配的 Webhook 创建一个 Webhook 事件（状态Pending），事件载荷就是完整的 Record JSON。

3️⃣ 投递：后台 Worker 每30 秒轮询一次，每次最多处理100 条待投递事件（见 object/webhook_worker.go 第 31-32 行）。HTTP 请求超时为 30 秒。

4️⃣ 判定结果：

状态	含义
`Pending`	待投递
`Success`	对方返回 2xx，投递成功
`Retrying`	投递失败，等待下次重试
`Failed`	达到最大重试次数，永久失败

5️⃣ 重试策略：默认每 60 秒重试一次、最多 3 次；也可开启指数退避（60s → 120s → 240s…，封顶 1 小时）。计算逻辑在 object/webhook_worker.go 的calculateNextRetryTime函数中。

三、5 步创建你的第一个 Webhook 回调

在 Casdoor 管理界面进入Webhooks页面（前端路由/webhooks，入口定义在 web/src/App.tsx），点击新增，按下面 5 步填写：

第 1 步：选择组织与回调 URL填上你的服务端地址，例如https://your-server.com/api/casdoor-callback。URL 即事件数据的接收地址。

第 2 步：选择方法、Content-Type 与自定义 Headers默认 POST + JSON。你可以在 Headers 里加Authorization: Bearer xxx之类的自定义头，用于你的接口鉴权。

第 3 步：勾选事件类型（Events）Casdoor 会对事件做精确匹配（见 object/record.go 的getFilteredWebhooks）。常用事件包括：

get-login：用户登录（含第三方登录）
get-signup：用户注册
update-user/add-user：用户信息变更与新增
send-webhook：Webhook 投递失败的告警记录

只勾你关心的事件，避免无谓流量。

第 4 步：配置字段过滤这是很多新手会忽略的"降噪"功能：

Object Fields：只推送事件对象中的指定字段，避免把整包数据推给对方
IsUserExtended + Token Fields：如果勾选"携带用户数据"，可进一步指定只附带用户的哪些字段（密码等敏感字段已自动脱敏）

第 5 步：设置重试参数并启用配置maxRetries（默认 3）、retryInterval（默认 60 秒）、是否启用指数退避，然后开启isEnabled。

四、失败怎么办？事件重放（Replay）来了 💪

对方服务宕机、网络抖动导致投递失败？不用慌：

打开Webhook Events页面（路由/webhook-events，代码见 web/src/pages/WebhookEventListPage.tsx），可按 Webhook、组织、状态（Pending/Success/Failed/Retrying）筛选
每条事件都能看到最后一次响应的状态码、响应体、错误信息，以及已尝试次数
对非Success的事件点击Replay，系统会重置重试计数并立即重新投递（对应 API：POST /api/replay-webhook-event，实现见 controllers/webhook_event.go 与 object/webhook_worker.go 的ReplayWebhookEvent）

五、回调接口开发指南：对方会收到什么？

你的服务收到的 POST 请求体是一个 JSON，结构为"Record + extendedUser"：

organization、user：事件所属组织与触发用户
action：事件类型，如get-login
object：事件详情（JSON 字符串，可被 Object Fields 过滤）
method、requestUri、statusCode、response：请求上下文
extendedUser：可选的（已脱敏的）用户扩展字段

⚠️ 开发自定义回调时的 3 个最佳实践：

快速返回 2xx：HTTP 超时是 30 秒，处理慢会触发重试，建议先收下再异步处理
按 event ID 做幂等：重试机制意味着同一事件可能被投递多次
只监听公网地址：非built-in组织的 Webhook 出站请求走"仅限公网"的 HTTP 客户端（见 object/webhook_util.go），禁止指向内网地址，这是内置的 SSRF 防护

六、API 参考：Webhook 与事件管理接口 📡

如果你想用程序化管理 Webhook（CI/CD 中批量配置、自动巡检），Casdoor 提供了两套 REST API：

Webhook 配置管理（见 controllers/webhook.go）：

GET /api/get-webhooks?owner=&organization=&p=&pageSize=分页查询
GET /api/get-webhook?id=owner/name查询单个
POST /api/add-webhook/POST /api/update-webhook/POST /api/delete-webhook增删改

Webhook 事件管理（见 controllers/webhook_event.go）：

GET /api/get-webhook-events?organization=&webhook=&state=&p=&pageSize=按条件筛选事件
GET /api/get-webhook-event-detail?id=owner/name事件详情
POST /api/replay-webhook-event?id=owner/name重放失败事件
POST /api/delete-webhook-event删除事件记录

🔐 权限提示：只有全局管理员才能关闭singleOrgOnly（让 Webhook 接收所有组织的事件）；普通组织管理员的 Webhook 会被强制限定在本组织范围内（见 controllers/webhook.go 第 117-121 行）。

七、写在最后

通过 Casdoor Webhook 事件系统，你只需 5 步配置，就能把登录、注册、用户变更等身份事件实时推送到任意自定义回调地址，配合重试、退避与重放机制，基本覆盖了生产环境的可靠性需求。接下来不妨试试：配置一个get-login事件推送到你的测试服务，再从 Webhook Events 页面观察一次完整的事件生命周期吧！🚀

创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考