Solicitud de Webhooks (Webhooks request)

Una vez que se emite un evento de hook válido, Logto buscará los webhooks correspondientes y enviará una solicitud POST por cada configuración de hook.

Encabezados de la solicitud

Key	Personalizable	Notas
user-agent	✅	Logto (https://logto.io/) por defecto.
content-type	✅	application/json por defecto.
logto-signature-sha-256		la firma del cuerpo de la solicitud, consulta asegura tus webhooks.

Puedes sobrescribir los encabezados personalizables personalizando los encabezados de la solicitud con la misma clave.

Cuerpo de la solicitud de eventos de interaction hook

Eventos disponibles: PostRegister, PostSignIn, PostResetPassword

El cuerpo de la solicitud es un objeto JSON que contiene tres tipos de campos de datos:

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

Campo	Tipo	Opcional	Notas
hookId	string		El identificador en Logto.
event	string		Qué evento dispara este hook.
createdAt	string		La fecha de creación del payload en formato ISO.
interactionEvent	string		El evento de interacción que dispara este hook.
sessionId	string	✅	El ID de sesión (no el ID de interacción) para este evento, si aplica.
userAgent	string	✅	El user-agent de la solicitud que dispara este hook.
userIp	string	✅	La dirección IP de la solicitud que dispara este hook.
userId	string	✅	El ID de usuario relacionado para este evento, si aplica.
user	UserEntity	✅	La entidad de usuario relacionada para este evento, si aplica.
applicationId	string	✅	El ID de aplicación relacionado para este evento, si aplica.
application	ApplicationEntity	✅	La información de la aplicación relacionada para este evento, si aplica.

Consulta la referencia de Usuarios y Aplicaciones para explicaciones detalladas de los campos.

Cuerpo de la solicitud de eventos de data mutation hook

Campos estándar del cuerpo de la solicitud

Campo	Tipo	Opcional	Notas
hookId	string		El identificador en Logto.
event	string		Qué evento dispara este hook.
createdAt	string		La fecha de creación del payload en formato ISO.
userAgent	string	✅	El user-agent de la solicitud.
ip	string	✅	La dirección IP de la solicitud.

Campos del cuerpo de contexto de Interaction API

Eventos de data mutation hook que son disparados por llamadas a la API de interacción de usuario.

Eventos disponibles: User.Created, User.Data.Updated

Campo	Tipo	Opcional	Notas
interactionEvent	string	✅	El evento de interacción que dispara este hook.
sessionId	string	✅	El ID de sesión (no el ID de interacción) para este evento, si aplica.
applicationId	string	✅	El ID de aplicación relacionado para este evento, si aplica.
application	ApplicationEntity	✅	La información de la aplicación relacionada para este evento, si aplica.

Campos del cuerpo de contexto de Management API

Eventos de data mutation hook que son disparados por llamadas a la Management API.

Campo	Tipo	Opcional	Notas
path	string	✅	La ruta de la llamada a la API que dispara este hook.
method	string	✅	El método de la llamada a la API que dispara este hook.
status	number	✅	El código de estado de la respuesta de la llamada a la API que dispara este hook.
params	object	✅	Los parámetros de ruta koa de la solicitud de la API que dispara este hook.
matchedRoute	string	✅	La ruta koa coincidente de la llamada a la API que dispara este hook. Logto usa este campo para emparejar los eventos habilitados de hook.

Campos del cuerpo de datos del payload

Eventos de usuario

Evento	Campo	Tipo	Opcional	Notas
User.Created	data	UserEntity		La entidad de usuario creada para este evento.
User.Data.Updated	data	UserEntity		La entidad de usuario actualizada para este evento.
User.Deleted	data	null	/

Eventos de rol (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;
};

Evento	Campo	Tipo	Opcional	Notas
Role.Created	data	Role		La entidad de rol creada para este evento.
Role.Data.Updated	data	Role		La entidad de rol actualizada para este evento.
Role.Deleted	data	null
Role.Scope.Updated	data	Scope[]		Los alcances (scopes) actualizados asignados al rol.
Role.Scope.Updated	roleId	string	✅	El ID del rol al que se asignan los alcances. (Solo disponible cuando el evento fue disparado por la creación de un nuevo rol con alcances preasignados)

Eventos de permiso (Scope)

Evento	Campo	Tipo	Opcional	Notas
Scope.Created	data	Scope		La entidad de alcance creada para este evento.
Scope.Data.Updated	data	Scope		La entidad de alcance actualizada para este evento.
Scope.Deleted	data	null	/

Eventos de organización (Organization)

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

Evento	Campo	Tipo	Opcional	Notas
Organization.Created	data	Organization		La entidad de organización creada para este evento.
Organization.Data.Updated	data	Organization		La entidad de organización actualizada para este evento.
Organization.Deleted	data	null	/
Organization.Membership.Updated	data	null	/

Eventos de OrganizationRole

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

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

Evento	Campo	Tipo	Opcional	Notas
OrganizationRole.Created	data	OrganizationRole		La entidad de rol de organización creada para este evento.
OrganizationRole.Data.Updated	data	OrganizationRole		La entidad de rol de organización actualizada para este evento.
OrganizationRole.Deleted	data	null	/
OrganizationRole.Scope.Updated	data	null	/
OrganizationRole.Scope.Updated	organizationRoleId	string	✅	El ID del rol al que se asignan los alcances. (Solo disponible cuando el evento fue disparado por la creación de un nuevo rol con alcances preasignados)

Eventos de permiso de organización (OrganizationScope)

Evento	Campo	Tipo	Opcional	Notas
OrganizationScope.Created	data	OrganizationScope		La entidad de alcance de organización creada.
OrganizationScope.Data.Updated	data	OrganizationScope		La entidad de alcance de organización actualizada.
OrganizationScope.Deleted	data	null	/

Cuerpo de la solicitud de eventos de excepción hook

Eventos disponibles: Identifier.Lockout

El cuerpo de la solicitud es un objeto JSON que contiene los campos estándar del cuerpo de la solicitud y campos adicionales como se muestra a continuación:

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

Campo	Tipo	Opcional	Notas
hookId	string		El identificador en Logto.
event	string		Qué evento dispara este hook.
createdAt	string		La fecha de creación del payload en formato ISO.
userAgent	string	✅	El user-agent de la solicitud.
ip	string	✅	La dirección IP de la solicitud.
interactionEvent	string	✅	El evento de interacción que dispara este hook.
sessionId	string	✅	El ID de sesión (no el ID de interacción) para este evento, si aplica.
applicationId	string	✅	El ID de aplicación relacionado para este evento, si aplica.
application	ApplicationEntity	✅	La información de la aplicación relacionada para este evento, si aplica.
type	SignInIdentifier		El tipo de identificador del usuario, por ejemplo, email, teléfono o nombre de usuario.
value	string		El valor del identificador del usuario que disparó el bloqueo.