Webhooks 请求

一旦有效的 hook 事件被触发，Logto 将找到相应的 webhooks，并根据每个 hook 配置发送一个 POST 请求。

请求头

Key	Customizable	Notes
user-agent	✅	默认是 Logto (https://logto.io/)。
content-type	✅	默认是 application/json。
logto-signature-sha-256		请求体的签名，参考 保护你的 webhooks。

你可以通过使用相同的 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;
};

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

Field	Type	Optional	Notes
hookId	string		在 Logto 中的标识符。
event	string		触发此 hook 的事件。
createdAt	string		负载的创建时间，ISO 格式。
interactionEvent	string		触发此 hook 的交互事件。
sessionId	string	✅	此事件的会话 ID（不是交互 ID），如果适用。
userAgent	string	✅	触发此 hook 的请求的 user-agent。
userIp	string	✅	触发此 hook 的请求的 IP 地址。
userId	string	✅	此事件相关的用户 ID，如果适用。
user	UserEntity	✅	此事件相关的用户实体，如果适用。
applicationId	string	✅	此事件相关的应用 ID，如果适用。
application	ApplicationEntity	✅	此事件相关的应用信息，如果适用。

参见 用户 和 应用 参考以获取详细的字段解释。

数据变更 hook 事件请求体

标准请求体字段

Field	Type	Optional	Notes
hookId	string		在 Logto 中的标识符。
event	string		触发此 hook 的事件。
createdAt	string		负载的创建时间，ISO 格式。
userAgent	string	✅	请求的 user-agent。
ip	string	✅	请求的 IP 地址。

交互 API 上下文体字段

由用户交互 API 调用触发的数据变更 hook 事件。

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

Field	Type	Optional	Notes
interactionEvent	string	✅	触发此 hook 的交互事件。
sessionId	string	✅	此事件的会话 ID（不是交互 ID），如果适用。
applicationId	string	✅	此事件相关的应用 ID，如果适用。
application	ApplicationEntity	✅	此事件相关的应用信息，如果适用。

管理 API 上下文体字段

由管理 API 调用触发的数据变更 hook 事件。

Field	Type	Optional	Notes
path	string	✅	触发此 hook 的 API 调用路径。
method	string	✅	触发此 hook 的 API 调用方法。
status	number	✅	触发此 hook 的 API 调用的响应状态码。
params	object	✅	触发此 hook 的 API 调用的请求 koa 路径参数。
matchedRoute	string	✅	触发此 hook 的 API 调用的 koa 匹配路由。Logto 使用此字段来匹配启用的 hook 事件。

数据负载体字段

用户事件

Event	Field	Type	Optional	Notes
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;
};

Event	Field	Type	Optional	Notes
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）事件

Event	Field	Type	Optional	Notes
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;
};

Event	Field	Type	Optional	Notes
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;
};

Event	Field	Type	Optional	Notes
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）事件

Event	Field	Type	Optional	Notes
OrganizationScope.Created	data	OrganizationScope		创建的组织权限实体。
OrganizationScope.Data.Updated	data	OrganizationScope		更新的组织权限实体。
OrganizationScope.Deleted	data	null	/