把身份事件推出去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 WebhookWebhook 事件系统是 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 产生一条记录Recordobject/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 步勾选事件类型EventsCasdoor 会对事件做精确匹配见 object/record.go 的getFilteredWebhooks。常用事件包括get-login用户登录含第三方登录get-signup用户注册update-user/add-user用户信息变更与新增send-webhookWebhook 投递失败的告警记录只勾你关心的事件避免无谓流量。第 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系统会重置重试计数并立即重新投递对应 APIPOST /api/replay-webhook-event实现见 controllers/webhook_event.go 与 object/webhook_worker.go 的ReplayWebhookEvent五、回调接口开发指南对方会收到什么你的服务收到的 POST 请求体是一个 JSON结构为Record extendedUserorganization、user事件所属组织与触发用户action事件类型如get-loginobject事件详情JSON 字符串可被 Object Fields 过滤method、requestUri、statusCode、response请求上下文extendedUser可选的已脱敏的用户扩展字段⚠️ 开发自定义回调时的 3 个最佳实践快速返回 2xxHTTP 超时是 30 秒处理慢会触发重试建议先收下再异步处理按 event ID 做幂等重试机制意味着同一事件可能被投递多次只监听公网地址非built-in组织的 Webhook 出站请求走仅限公网的 HTTP 客户端见 object/webhook_util.go禁止指向内网地址这是内置的 SSRF 防护六、API 参考Webhook 与事件管理接口 如果你想用程序化管理 WebhookCI/CD 中批量配置、自动巡检Casdoor 提供了两套 REST APIWebhook 配置管理见 controllers/webhook.goGET /api/get-webhooks?ownerorganizationppageSize分页查询GET /api/get-webhook?idowner/name查询单个POST /api/add-webhook/POST /api/update-webhook/POST /api/delete-webhook增删改Webhook 事件管理见 controllers/webhook_event.goGET /api/get-webhook-events?organizationwebhookstateppageSize按条件筛选事件GET /api/get-webhook-event-detail?idowner/name事件详情POST /api/replay-webhook-event?idowner/name重放失败事件POST /api/delete-webhook-event删除事件记录 权限提示只有全局管理员才能关闭singleOrgOnly让 Webhook 接收所有组织的事件普通组织管理员的 Webhook 会被强制限定在本组织范围内见 controllers/webhook.go 第 117-121 行。七、写在最后通过 Casdoor Webhook 事件系统你只需 5 步配置就能把登录、注册、用户变更等身份事件实时推送到任意自定义回调地址配合重试、退避与重放机制基本覆盖了生产环境的可靠性需求。接下来不妨试试配置一个get-login事件推送到你的测试服务再从 Webhook Events 页面观察一次完整的事件生命周期吧【免费下载链接】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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考