Webhooks 事件

本指南列出不同的 Logto Webhook 事件，並說明每個事件發生的時機。

使用者互動 Webhook 事件

Event type	Description
PostRegister	使用者透過 UI 介面成功建立新帳號。
PostSignIn	使用者透過 UI 介面成功登入。
PostResetPassword	使用者透過「忘記密碼」流程成功重設密碼。

資料變更 Webhook 事件

使用者

Event type	Description
User.Created	建立新使用者帳號。
User.Deleted	刪除使用者帳號。
User.Data.Updated	更新使用者個人資料，例如 email、頭像、custom.data、社交識別碼等。
User.SuspensionStatus.Updated	使用者停權狀態變更（停權或重新啟用）。

角色 (Role)

Event type	Description
Role.Created	建立新角色 (Role)。
Role.Deleted	刪除角色 (Role)。
Role.Data.Updated	更新角色 (Role) 資料，例如角色名稱、描述、預設角色狀態。
Role.Scopes.Updated	新增或移除指派給角色 (Role) 的權限 (Permissions)。

權限 (Scope)

Event type	Description
Scope.Created	建立新的 API 權限 (Permission)。
Scope.Deleted	刪除 API 權限 (Permission)。
Scope.Data.Updated	更新 API 權限 (Permission) 資料，例如權限描述。

組織 (Organization)

Event type	Description
Organization.Created	建立新組織 (Organization)。
Organization.Deleted	刪除組織 (Organization)。
Organization.Data.Updated	更新組織 (Organization) 資料，例如組織名稱、描述、custom.data 等。
Organization.Membership.Updated	使用者或應用程式被加入或移出組織 (Organization)。Payload 包含 membership delta fields。

組織角色 (Organization role)

Event type	Description
OrganizationRole.Created	建立新組織角色 (Organization role)。
OrganizationRole.Deleted	刪除組織角色 (Organization role)。
OrganizationRole.Data.Updated	更新組織角色 (Organization role) 資料，例如名稱與描述。
OrganizationRole.Scopes.Updated	新增或移除指派給組織角色 (Organization role) 的權限 (Permissions)。

組織權限 (Organization permission, scope)

Event type	Description
OrganizationScope.Created	建立新組織權限 (Organization permission)。
OrganizationScope.Deleted	刪除組織權限 (Organization permission)。
OrganizationScope.Data.Updated	更新組織權限 (Organization permission) 資料，例如描述。

信任裝置 (Trusted device)

Event type	Description
TrustedDevice.Created	成功驗證互動後建立信任裝置 (Trusted-device) 記錄。
TrustedDevice.Deleted	使用者或管理員移除信任裝置 (Trusted-device) 記錄。

自然過期不會觸發 TrustedDevice.Expired webhook，因為過期屬於基於時間的有效性變化，而非應用程式資料變更。TrustedDevice.Created payload 會包含 expiresAt，消費端可自行推算預期過期時間。成功使用及信任裝置政策變更不會觸發生命週期 webhook。

Management API 觸發事件

API endpoint	Event
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 interaction action	Event
使用者 email / phone 綁定	User.Data.Updated
使用者 MFA 綁定	User.Data.Updated
使用者社交 / SSO 綁定	User.Data.Updated
使用者密碼重設	User.Data.Updated
使用者註冊	User.Created
使用者透過即時佈建 (Just-in-time provisioning)（符合 email 網域或企業級 SSO 連接器）自動加入組織	Organization.Membership.Updated

例外 Webhook 事件

安全性 (Security)

Event type	Description
Identifier.Lockout	使用者帳號因連續身分驗證失敗而被鎖定。可能在以下流程觸發：密碼驗證失敗驗證碼驗證失敗一次性權杖驗證失敗
Message.RateLimited	終端使用者超過每收件人發送速率限制的驗證碼發送次數。僅在終端使用者發送路徑（Experience API 與 Account API）觸發，payload 為 `{ action, recipient }`。
Grant.LimitExceeded	成功授權使使用者超過應用程式的最大同時驗證裝置數限制 (`maxAllowedGrants`)，Logto 會撤銷該應用程式最舊的授權。

常見問題

`PostRegister` 和 `User.Created` 有什麼不同？

PostRegister 於使用者透過註冊流程成功建立新帳號時觸發；User.Created 則於透過 Management API 建立新使用者帳號時觸發。

使用者互動 Webhook 事件​

資料變更 Webhook 事件​

使用者​

角色 (Role)​

權限 (Scope)​

組織 (Organization)​

組織角色 (Organization role)​

組織權限 (Organization permission, scope)​

信任裝置 (Trusted device)​

Management API 觸發事件​

Experience API 觸發事件​

例外 Webhook 事件​

安全性 (Security)​

常見問題​

PostRegister 和 User.Created 有什麼不同？​