Webhook 请求

当一个有效的 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	✅	此事件相关的用户 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	/

角色 (Role) 事件

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) 的已更新权限 (Scope)。
Role.Scope.Updated	roleId	string	✅	分配权限 (Scope) 的角色 (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	✅	分配权限 (Scope) 的组织角色 (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	✅	此事件相关的应用 ID，如适用。
application	ApplicationEntity	✅	此事件相关的应用信息，如适用。
type	SignInIdentifier		用户的标识符类型，例如 email、phone 或 username。
value	string		触发锁定的用户标识符值。