Webhooks 事件
本指南列出了不同的 Logto Webhook 事件，并解释了每个事件发生的时机。
用户交互 Webhook 事件
| 事件类型 | 描述 |
|---|---|
| PostRegister | 用户通过 UI 界面成功创建新账户。 |
| PostSignIn | 用户通过 UI 界面成功登录。 |
| PostResetPassword | 用户通过“忘记密码”流程成功重置密码。 |
数据变更 Webhook 事件
用户
| 事件类型 | 描述 |
|---|---|
| User.Created | 创建了新的用户账户。 |
| User.Deleted | 用户账户被删除。 |
| User.Data.Updated | 用户资料数据被更新，例如邮箱、头像、custom.data、社交标识等。 |
| User.SuspensionStatus.Updated | 用户的封禁状态发生变化（被封禁或重新激活）。 |
角色 (Role)
| 事件类型 | 描述 |
|---|---|
| Role.Created | 创建了新的角色 (Role)。 |
| Role.Deleted | 角色 (Role) 被删除。 |
| Role.Data.Updated | 角色 (Role) 的数据被更新，例如角色名称、描述和默认角色状态。 |
| Role.Scopes.Updated | 分配给角色 (Role) 的权限 (Permissions) 被添加或移除。 |
权限 (Scope)
| 事件类型 | 描述 |
|---|---|
| Scope.Created | 创建了新的 API 权限 (Permission)。 |
| Scope.Deleted | API 权限 (Permission) 被删除。 |
| Scope.Data.Updated | API 权限 (Permission) 的数据被更新，例如权限描述。 |
组织 (Organization)
| 事件类型 | 描述 |
|---|---|
| Organization.Created | 创建了新的组织 (Organization)。 |
| Organization.Deleted | 组织 (Organization) 被删除。 |
| Organization.Data.Updated | 组织 (Organization) 的数据被更新，例如组织名称、描述、custom.data 等。 |
| Organization.Membership.Updated | 用户或应用程序被添加到或移出组织 (Organization)。负载包含 成员变更字段。 |
组织角色 (Organization role)
| 事件类型 | 描述 |
|---|---|
| OrganizationRole.Created | 创建了新的组织角色 (Organization role)。 |
| OrganizationRole.Deleted | 组织角色 (Organization role) 被删除。 |
| OrganizationRole.Data.Updated | 组织角色 (Organization role) 的数据被更新，例如组织角色名称和描述。 |
| OrganizationRole.Scopes.Updated | 分配给组织角色 (Organization role) 的权限 (Permissions) 被添加或移除。 |
组织权限 (Organization permission, scope)
| 事件类型 | 描述 |
|---|---|
| OrganizationScope.Created | 创建了新的组织权限 (Organization permission)。 |
| OrganizationScope.Deleted | 组织权限 (Organization permission) 被删除。 |
| OrganizationScope.Data.Updated | 组织权限 (Organization permission) 的数据被更新，例如组织权限描述。 |
可信设备 (Trusted device)
| 事件类型 | 描述 |
|---|---|
| TrustedDevice.Created | 成功认证 (Authentication) 交互后创建了可信设备记录。 |
| TrustedDevice.Deleted | 用户或管理员移除了可信设备记录。 |
自然过期不会触发 TrustedDevice.Expired webhook，因为过期是基于时间的有效性变化，而不是应用变更。TrustedDevice.Created 的负载包含 expiresAt 字段，因此使用者可以推导出预期的过期时间。成功使用和可信设备策略变更不会触发生命周期 webhook。
Management API 触发的事件
| API 端点 | 事件 |
|---|---|
| POST /users | User.Created |
| DELETE /users/:userId | User.Deleted |
| PATCH /users/:userId | User.Data.Updated |
| PATCH /users/:userId/custom-data | User.Data.Updated |
| PATCH /users/:userId/profile | User.Data.Updated |
| PATCH /users/:userId/password | User.Data.Updated |
| PATCH /users/:userId/is-suspended | User.SuspensionStatus.Updated |
| POST /roles | Role.Created, (Role.Scopes.Update) |
| DELETE /roles/:id | Role.Deleted |
| PATCH /roles/:id | Role.Data.Updated |
| POST /roles/:id/scopes | Role.Scopes.Updated |
| DELETE /roles/:id/scopes/:scopeId | Role.Scopes.Updated |
| POST /resources/:resourceId/scopes | Scope.Created |
| DELETE /resources/:resourceId/scopes/:scopeId | Scope.Deleted |
| PATCH /resources/:resourceId/scopes/:scopeId | Scope.Data.Updated |
| POST /organizations | Organization.Created |
| DELETE /organizations/:id | Organization.Deleted |
| PATCH /organizations/:id | Organization.Data.Updated |
| PUT /organizations/:id/users | Organization.Membership.Updated |
| POST /organizations/:id/users | Organization.Membership.Updated |
| DELETE /organizations/:id/users/:userId | Organization.Membership.Updated |
| PUT /organizations/:id/applications | Organization.Membership.Updated |
| POST /organizations/:id/applications | Organization.Membership.Updated |
| DELETE /organizations/:id/applications/:applicationId | Organization.Membership.Updated |
| PUT /organization-invitations/:id/status (Accepted) | Organization.Membership.Updated |
| POST /organization-roles | OrganizationRole.Created, (OrganizationRole.Scopes.Updated) |
| DELETE /organization-roles/:id | OrganizationRole.Deleted |
| PATCH /organization-roles/:id | OrganizationRole.Data.Updated |
| POST /organization-scopes | OrganizationScope.Created |
| DELETE /organization-scopes/:id | OrganizationScope.Deleted |
| PATCH /organization-scopes/:id | OrganizationScope.Data.Updated |
| PUT /organization-roles/:id/scopes | OrganizationRole.Scopes.Updated |
| POST /organization-roles/:id/scopes | OrganizationRole.Scopes.Updated |
| DELETE /organization-roles/:id/scopes/:organizationScopeId | OrganizationRole.Scopes.Updated |
Experience API 触发的事件
| 用户交互操作 | 事件 |
|---|---|
| 用户邮箱 / 手机号绑定 | User.Data.Updated |
| 用户 MFA 绑定 | User.Data.Updated |
| 用户社交 / SSO 绑定 | User.Data.Updated |
| 用户密码重置 | User.Data.Updated |
| 用户注册 | User.Created |
| 用户通过 即时供应（匹配邮箱域名或企业 SSO 连接器）自动加入组织 (Organization) | Organization.Membership.Updated |
异常 Webhook 事件
安全 (Security)
| 事件类型 | 描述 |
|---|---|
| Identifier.Lockout | 由于连续身份验证失败，用户账户被锁定。可在以下流程中触发：
|
| Message.RateLimited | 终端用户超过了每个收件人的 发送速率限制（用于验证码）。仅在终端用户发送路径（Experience API 和 Account API）触发，负载为 { action, recipient }。 |
| Grant.LimitExceeded | 成功授权 (Authorization) 导致用户超过应用的 最大并发认证 (Authentication) 设备数（maxAllowedGrants），Logto 会撤销其最早的授权。 |
常见问题
PostRegister 和 User.Created 有什么区别？
PostRegister 和 User.Created 有什么区别？PostRegister 在用户通过用户注册流程成功创建新账户时触发；User.Created 在通过 Management API 创建新用户账户时触发。