Webhook列表
事件发生时，Casdoor 可以向你配置的地址发送带 JSON 负载的 HTTP POST 请求，通知你的应用。使用webhook对注册、登录、登出、个人资料更新以及许多其他事件作出响应。
Webhooks的工作原理
当Casdoor中发生事件时：
- Casdoor 会向指定的 webhook 地址发送
POST请求。 - 请求包含带有事件详情的JSON有效载荷。
- 您的应用程序会处理该有效载荷，并根据事件类型执行相关操作。
支持的事件
Webhook可订阅一系列按领域分组的事件：
身份验证&会话事件
signup、login、logout：用户认证流程sso-logout,unlink- 单点登录与账户解除绑定new-user- 新用户创建的自定义事件new-user-ldap：通过 LDAP 同步创建新用户时触发的自定义事件new-user-syncer：通过数据库同步器创建新用户时触发的自定义事件
资源管理事件
所有核心资源（组织、群组、用户、应用、提供商和证书）都支持标准的增删改操作（add-*、update-*、delete-*）。角色、权限、模型、适配器、强制器、会话、令牌、产品、支付和定价等其他资源也支持这些操作。 Webhook 还可跟踪同步器、表单、邀请、LDAP 配置、订单、工单和交易的更改。
专业运营
用户管理： 添加用户密钥, 从组中移除用户, 上传用户, 检查用户密码, 设置密码, 重置邮箱或电话, 验证身份
批量操作： 上传组, 上传角色, 上传权限, 上传资源
订单处理： 下单, 取消订单, 支付订单
付款处理： 发票付款, 通知付款
邀请： 发送邀请, 验证邀请
支持系统： 添加工单消息
同步： run-syncer, test-syncer-db, sync-ldap-users
访问控制： 强制执行, 批量强制执行, 添加策略, 更新策略, 删除策略, 添加记录
多因素身份验证： 删除多因素身份验证, 设置首选多因素身份验证, 多因素身份验证/设置/初始化, 多因素身份验证/设置/验证, 多因素身份验证/设置/启用
WebAuthn： webauthn/注册/开始, webauthn/注册/完成, webauthn/登录/开始, webauthn/登录/完成
OAuth&令牌管理： login/oauth/access_token, login/oauth/refresh_token, login/oauth/introspect
验证&通信： 发送验证码, 验证验证码, 验证验证码, 发送电子邮件, 发送短信, 发送通知
SAML：acs、saml/metadata
系统操作： 运行casbin命令, 刷新引擎, 健康, 指标, 回调, 设备认证, 人脸识别登录开始, 用户, 用户信息
每个事件都在 webhook 负载中包含上下文信息，使您能够根据触发 webhook 的具体操作实施自定义逻辑 。
设置Webhook
- 在您的Casdoor实例中，前往设置 → Webhook.
- 单击添加Webhook.
- 输入Webhook URL以接收事件。
- 选择一个或多个要订阅的事件。
- （可选）添加自定义标头（例如用于身份验证）。
- 保存。 Casdoor将从此处开始向该URL发送事件。
筛选 Webhook 负载
在使用webhook时，您并不总是需要完整的记录数据。 Casdoor允许您通过配置对象字段来过滤有效负载，以适用于每个webhook。当您有隐私顾虑、带宽受限，或您的端点仅处理特定字段时，此功能尤为宝贵。
ObjectFields 配置可接受“全部”以接收完整记录，也可接受您希望包含的特定字段名称列表。当您指定字段名称时，Casdoor仅会在webhook有效载荷中发送这些字段，从而减小有效载荷大小，并且仅公开您的应用程序所需的数据。
如果您配置了多个具有不同ObjectField设置的webhook，每个webhook将独立运行。例如，一个webhook可能仅接收用户ID和时间戳，而另一个则接收完整的用户资料。 Casdoor 确保应用于某个 Webhook 的过滤不会影响发送给其他 Webhook 的数据，即使这些 Webhook 是由同一事件触发的。
示例有效负载
登录时发送到您的 webhook 的示例 JSON：
{
"event": "login",
"timestamp": 1709452800,
"user": {
"id": "12345",
"username": "johndoe",
"email": "johndoe@example.com"
}
}
您的应用程序应解析此有效载荷并执行必要操作，例如记录事件或通知其他服务。
登录失败分类
每次登录尝试都会保存为一条记录（在管理后台的 Records 中可见，也会随 webhook 载荷发送）。登录失败时，Casdoor 会在记录的 detail 字段中填入一个稳定的、机器可读的原因，无需解析本地化的错误信息就能对失败分类。
可能的原因有：
详情 | 含义 |
|---|---|
user-not-found | 没有与所提供标识匹配的用户。 |
account-disabled | 用户账号已被禁用（封禁）。 |
account-frozen | 用户账号已被冻结 / 锁定。 |
wrong-password | 密码不匹配。 |
password-expired | 密码已过期，必须重置。 |
mfa-failed | 多因素认证验证失败。 |
登录成功时 detail 为空。可以用这些值做审计看板、告警（例如 wrong-password 激增），或者按特定失败原因实现锁定逻辑。
测试Webhook
在投入生产前，请使用以下内容进行测试：
- Beeceptor——允许您创建自定义Webhook URL并检查传入请求。
- Webhook.site——提供一个用于测试的即时Webhook端点。
使用Beeceptor的示例
- 在Beeceptor.
- 复制该URL，并将其设置为Casdoor中的Webhook URL。
- 触发一个事件（例如，登录Casdoor）。
- 在Beeceptor的仪表板中检查请求。
在您的应用程序中处理Webhook
您的服务器应能够处理传入的Webhook请求。以下是Node.js中的简单示例：
const express = require('express');
const app = express();
app.use(express.json());
app.post('/webhook', (req, res) => {
console.log('Received webhook:', req.body);
res.status(200).send('Webhook received');
});
app.listen(3000, () => console.log('Server running on port 3000'));
在生产环境中使用webhook之前，请先使用Beeceptor或Webhook.site验证传 入的webhook请求（例如签名或共享密钥）并进行测试
配送跟踪与重试
Casdoor 会将每次 Webhook 投递尝试都作为Webhook 事件记录。在侧栏中导航至Webhook 事件,以查看您组织中所有 Webhook 的交付历史。
每条事件记录包含：
| 字段 | 描述 |
|---|---|
| 状态 | 待处理, 成功, 失败,或重试中 |
| 尝试次数 | 已进行的配送尝试次数 |
| 上次状态码 | 最近一次尝试的HTTP响应码 |
| 上次响应/错误 | 最近一次尝试的响应体或错误信息 |
| 下次重试时间 | 下次自动重试的时间（如适用） |
自动重试
失败的投递会由每30秒运行一次的后台工作程序自动重试。每个事件的默认最大重试次数为3。所有重试均耗尽后，事件状态将被设置为失败且不会自动进行后续尝试。
手动重放
要重新发送事件，请在Webhook 事件列表中打开它，然后单击重播. This creates a new delivery attempt regardless of the current retry count or status. 这将创建一个新的投递尝试，而不管当前的重试次数或状态。用于在临时端点中断后恢复，或在修复处理程序中的错误后重新处理事件。