Webhooks 請求

一旦發出有效的 hook 事件，Logto 將尋找相應的 webhooks 並根據每個 hook 配置發送 POST 請求。

請求標頭

Key	可自訂	備註
user-agent	✅	預設為 Logto (https://logto.io/)。
content-type	✅	預設為 application/json。
logto-signature-sha-256		請求主體的簽名，參考 保護你的 webhooks。

你可以透過 自訂請求 標頭來覆寫可自訂的標頭。

互動 hook 事件請求主體

可用事件：PostRegister、PostSignIn、PostResetPassword

請求主體是一個包含三種類型資料欄位的 JSON 物件：

type UserEntity = {
  id: string;
  username?: string;
  primaryEmail?: string;
  primaryPhone?: string;
  name?: string;
  avatar?: string;
  customData?: object;
  identities?: object;
  lastSignInAt?: string;
  createdAt?: string;
  applicationId?: string;
  isSuspended?: boolean;
};

type ApplicationEntity = {
  id: string;
  name: string;
  description?: string;
};

欄位	類型	可選擇	備註
hookId	string		Logto 中的識別符。
event	string		觸發此 hook 的事件。
createdAt	string		負載的建立時間，ISO 格式。
interactionEvent	string		觸發此 hook 的互動事件。
sessionId	string	✅	此事件的 Session ID（非 Interaction ID），若適用。
userAgent	string	✅	觸發此 hook 的請求的 user-agent。
userIp	string	✅	觸發此 hook 的請求的 IP 位址。
userId	string	✅	此事件相關的使用者 ID，若適用。
user	UserEntity	✅	此事件相關的使用者實體，若適用。
applicationId	string	✅	此事件相關的應用程式 ID，若適用。
application	ApplicationEntity	✅	此事件相關的應用程式資訊，若適用。

詳細欄位說明請參閱 使用者 和 應用程式 參考資料。

資料變更 hook 事件請求主體

標準請求主體欄位

欄位	類型	可選擇	備註
hookId	string		Logto 中的識別符。
event	string		觸發此 hook 的事件。
createdAt	string		負載的建立時間，ISO 格式。
userAgent	string	✅	請求的 user-agent。
ip	string	✅	請求的 IP 位址。

互動 API 上下文主體欄位

由使用者互動 API 呼叫觸發的資料變更 hook 事件。

可用事件：User.Created、User.Data.Updated

欄位	類型	可選擇	備註
interactionEvent	string	✅	觸發此 hook 的互動事件。
sessionId	string	✅	此事件的 Session ID（非 Interaction ID），若適用。
applicationId	string	✅	此事件相關的應用程式 ID，若適用。
application	ApplicationEntity	✅	此事件相關的應用程式資訊，若適用。

Management API 上下文主體欄位

由 Management API 呼叫觸發的資料變更 hook 事件。

欄位	類型	可選擇	備註
path	string	✅	觸發此 hook 的 API 呼叫路徑。
method	string	✅	觸發此 hook 的 API 呼叫方法。
status	number	✅	觸發此 hook 的 API 呼叫的回應狀態碼。
params	object	✅	觸發此 hook 的 API 呼叫的請求 koa 路徑參數。
matchedRoute	string	✅	觸發此 hook 的 API 呼叫的 koa 匹配路由。 Logto 使用此欄位來匹配啟用的 hook 事件。

資料負載主體欄位

使用者事件

事件	欄位	類型	可選擇	備註
User.Created	data	UserEntity		此事件創建的使用者實體。
User.Data.Updated	data	UserEntity		此事件更新的使用者實體。
User.Deleted	data	null	/

角色事件

type Role = {
  id: string;
  name: string;
  description: string;
  type: 'User' | 'MachineToMachine';
  isDefault: boolean;
};

type Scope = {
  id: string;
  name: string;
  description: string;
  resourceId: string;
  createdAt: number;
};

事件	欄位	類型	可選擇	備註
Role.Created	data	Role		此事件創建的角色實體。
Role.Data.Updated	data	Role		此事件更新的角色實體。
Role.Deleted	data	null
Role.Scope.Updated	data	Scope[]		分配給角色的更新後的權限範圍。
Role.Scope.Updated	roleId	string	✅	權限範圍分配到的角色 ID。（僅在事件由創建具有預先分配權限範圍的新角色觸發時可用）

權限（Scope）事件

事件	欄位	類型	可選擇	備註
Scope.Created	data	Scope		此事件創建的權限範圍實體。
Scope.Data.Updated	data	Scope		此事件更新的權限範圍實體。
Scope.Deleted	data	null	/

組織事件

type Organization = {
  id: string;
  name: string;
  description?: string;
  customData: object;
  createdAt: number;
};

事件	欄位	類型	可選擇	備註
Organization.Created	data	Organization		此事件創建的組織實體。
Organization.Data.Updated	data	Organization		此事件更新的組織實體。
Organization.Deleted	data	null	/
Organization.Membership.Updated	data	null	/

組織角色事件

type OrganizationRole = {
  id: string;
  name: string;
  description?: string;
};

type OrganizationScope = {
  id: string;
  name: string;
  description?: string;
};

事件	欄位	類型	可選擇	備註
OrganizationRole.Created	data	OrganizationRole		此事件創建的組織角色實體。
OrganizationRole.Data.Updated	data	OrganizationRole		此事件更新的組織角色實體。
OrganizationRole.Deleted	data	null	/
OrganizationRole.Scope.Updated	data	null	/
OrganizationRole.Scope.Updated	organizationRoleId	string	✅	權限範圍分配到的角色 ID。（僅在事件由創建具有預先分配權限範圍的新角色觸發時可用）

組織權限（OrganizationScope）事件

事件	欄位	類型	可選擇	備註
OrganizationScope.Created	data	OrganizationScope		創建的組織權限範圍實體。
OrganizationScope.Data.Updated	data	OrganizationScope		更新的組織權限範圍實體。
OrganizationScope.Deleted	data	null	/