Webhooks 請求 (Webhooks request)

當有效的 hook 事件被觸發時，Logto 會尋找對應的 webhook，並依每個 hook 設定發送一個 POST 請求。

請求標頭

Key	可自訂	說明
user-agent	✅	預設為 Logto (https://logto.io/)。
content-type	✅	預設為 application/json。
logto-signature-sha-256		請求主體的簽章，詳見保護你的 webhook。

你可以透過自訂請求標頭（key 相同時）覆寫可自訂的標頭。

互動 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;
};

enum ApplicationType {
  Native = 'Native',
  SPA = 'SPA',
  Traditional = 'Traditional',
  MachineToMachine = 'MachineToMachine',
  Protected = 'Protected',
  SAML = 'SAML',
}

type ApplicationEntity = {
  id: string;
  type: ApplicationType;
  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	✅	此事件相關的 User ID，如適用。
user	UserEntity	✅	此事件相關的使用者實體，如適用。
applicationId	string	✅	此事件相關的 Application ID，如適用。
application	ApplicationEntity	✅	此事件相關的應用程式資訊，如適用。

詳細欄位說明請參閱 使用者與應用程式參考文件。

資料變更 hook 事件請求主體

標準請求主體欄位

欄位	型別	選填	說明
hookId	string		Logto 中的識別碼。
event	string		觸發此 hook 的事件。
createdAt	string		負載建立時間（ISO 格式）。
userAgent	string	✅	請求的 user-agent。
ip	string	✅	請求的 IP 位址。

互動 API context 主體欄位

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

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

欄位	型別	選填	說明
interactionEvent	string	✅	觸發此 hook 的互動事件。
sessionId	string	✅	此事件的 Session ID（非 Interaction ID），如適用。
applicationId	string	✅	此事件相關的 Application ID，如適用。
application	ApplicationEntity	✅	此事件相關的應用程式資訊，如適用。

Management API context 主體欄位

由 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) 實體。
Role.Data.Updated	data	Role		此事件更新的角色 (Role) 實體。
Role.Deleted	data	null
Role.Scope.Updated	data	Scope[]		指派給角色 (Role) 的最新權限範圍 (Scopes)。
Role.Scope.Updated	roleId	string	✅	權限範圍 (Scopes) 指派到的角色 (Role) ID。（僅於建立新角色並預先指派權限範圍時提供）

權限（Scope）事件

事件	欄位	型別	選填	說明
Scope.Created	data	Scope		此事件建立的權限範圍 (Scope) 實體。
Scope.Data.Updated	data	Scope		此事件更新的權限範圍 (Scope) 實體。
Scope.Deleted	data	null	/

組織 (Organization) 事件

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

事件	欄位	型別	選填	說明
Organization.Created	data	Organization		此事件建立的組織 (Organization) 實體。
Organization.Data.Updated	data	Organization		此事件更新的組織 (Organization) 實體。
Organization.Deleted	data	null	/
Organization.Membership.Updated	data	null	/

組織角色 (OrganizationRole) 事件

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

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

事件	欄位	型別	選填	說明
OrganizationRole.Created	data	OrganizationRole		此事件建立的組織角色 (OrganizationRole) 實體。
OrganizationRole.Data.Updated	data	OrganizationRole		此事件更新的組織角色 (OrganizationRole) 實體。
OrganizationRole.Deleted	data	null	/
OrganizationRole.Scope.Updated	data	null	/
OrganizationRole.Scope.Updated	organizationRoleId	string	✅	權限範圍 (Scopes) 指派到的組織角色 (OrganizationRole) ID。（僅於建立新角色並預先指派權限範圍時提供）

組織權限（OrganizationScope）事件

事件	欄位	型別	選填	說明
OrganizationScope.Created	data	OrganizationScope		此事件建立的組織權限範圍 (OrganizationScope) 實體。
OrganizationScope.Data.Updated	data	OrganizationScope		此事件更新的組織權限範圍 (OrganizationScope) 實體。
OrganizationScope.Deleted	data	null	/

例外 hook 事件請求主體

可用事件：Identifier.Lockout

請求主體是一個 JSON 物件，包含標準請求主體欄位與下列額外欄位：

enum SignInIdentifier {
  Email = 'email',
  Phone = 'phone',
  Username = 'username',
}

欄位	型別	選填	說明
hookId	string		Logto 中的識別碼。
event	string		觸發此 hook 的事件。
createdAt	string		負載建立時間（ISO 格式）。
userAgent	string	✅	請求的 user-agent。
ip	string	✅	請求的 IP 位址。
interactionEvent	string	✅	觸發此 hook 的互動事件。
sessionId	string	✅	此事件的 Session ID（非 Interaction ID），如適用。
applicationId	string	✅	此事件相關的 Application ID，如適用。
application	ApplicationEntity	✅	此事件相關的應用程式資訊，如適用。
type	SignInIdentifier		使用者的識別類型，例如 email、phone 或 username。
value	string		觸發鎖定的使用者識別值。