Requête Webhooks

Lorsqu'un événement de hook valide est émis, Logto recherche les webhooks correspondants et envoie une requête POST par configuration de hook.

En-têtes de requête

Clé	Personnalisable	Remarques
user-agent	✅	Logto (https://logto.io/) par défaut.
content-type	✅	application/json par défaut.
logto-signature-sha-256		la signature du corps de la requête, voir sécuriser vos webhooks.

Vous pouvez écraser les en-têtes personnalisables en personnalisant les en-têtes de requête avec la même clé.

Corps de la requête des événements d'interaction hook

Événements disponibles : PostRegister, PostSignIn, PostResetPassword

Le corps de la requête est un objet JSON qui contient trois types de champs de données :

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

Champ	Type	Optionnel	Remarques
hookId	string		L'identifiant dans Logto.
event	string		L'événement qui déclenche ce hook.
createdAt	string		La date de création du payload au format ISO.
interactionEvent	string		L'événement d'interaction qui déclenche ce hook.
sessionId	string	✅	L'ID de session (et non l'ID d'interaction) pour cet événement, si applicable.
userAgent	string	✅	Le user-agent pour la requête qui déclenche ce hook.
userIp	string	✅	L'adresse IP pour la requête qui déclenche ce hook.
userId	string	✅	L'ID utilisateur associé à cet événement, si applicable.
user	UserEntity	✅	L'entité utilisateur associée à cet événement, si applicable.
applicationId	string	✅	L'ID d'application associé à cet événement, si applicable.
application	ApplicationEntity	✅	Les informations de l'application associée à cet événement, si applicable.

Voir la référence Utilisateurs et Applications pour des explications détaillées des champs.

Corps de la requête des événements de mutation de données hook

Champs standards du corps de la requête

Champ	Type	Optionnel	Remarques
hookId	string		L'identifiant dans Logto.
event	string		L'événement qui déclenche ce hook.
createdAt	string		La date de création du payload au format ISO.
userAgent	string	✅	Le user-agent pour la requête.
ip	string	✅	L'adresse IP pour la requête.

Champs du corps de contexte Interaction API

Événements de mutation de données hook déclenchés par des appels API d'interaction utilisateur.

Événements disponibles : User.Created, User.Data.Updated

Champ	Type	Optionnel	Remarques
interactionEvent	string	✅	L'événement d'interaction qui déclenche ce hook.
sessionId	string	✅	L'ID de session (et non l'ID d'interaction) pour cet événement, si applicable.
applicationId	string	✅	L'ID d'application associé à cet événement, si applicable.
application	ApplicationEntity	✅	Les informations de l'application associée à cet événement, si applicable.

Champs du corps de contexte Management API

Événements de mutation de données hook déclenchés par des appels Management API.

Champ	Type	Optionnel	Remarques
path	string	✅	Le chemin de l'appel API qui déclenche ce hook.
method	string	✅	La méthode de l'appel API qui déclenche ce hook.
status	number	✅	Le code de statut de la réponse de l'appel API qui déclenche ce hook.
params	object	✅	Les paramètres de chemin koa de la requête de l'appel API qui déclenche ce hook.
matchedRoute	string	✅	La route koa correspondante de l'appel API qui déclenche ce hook. Logto utilise ce champ pour faire correspondre les événements hook activés.

Champs du corps de la charge utile de données

Événements utilisateur

Événement	Champ	Type	Optionnel	Remarques
User.Created	data	UserEntity		L'entité utilisateur créée pour cet événement.
User.Data.Updated	data	UserEntity		L'entité utilisateur mise à jour pour cet événement.
User.Deleted	data	null	/

Événements Rôle (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;
};

Événement	Champ	Type	Optionnel	Remarques
Role.Created	data	Role		L'entité rôle créée pour cet événement.
Role.Data.Updated	data	Role		L'entité rôle mise à jour pour cet événement.
Role.Deleted	data	null
Role.Scope.Updated	data	Scope[]		Les portées mises à jour attribuées au rôle.
Role.Scope.Updated	roleId	string	✅	L'ID du rôle auquel les portées sont attribuées. (Disponible uniquement lorsque l'événement a été déclenché par la création d'un nouveau rôle avec des portées pré-attribuées)

Événements Permission (Scope)

Événement	Champ	Type	Optionnel	Remarques
Scope.Created	data	Scope		L'entité portée créée pour cet événement.
Scope.Data.Updated	data	Scope		L'entité portée mise à jour pour cet événement.
Scope.Deleted	data	null	/

Événements Organisation (Organization)

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

Événement	Champ	Type	Optionnel	Remarques
Organization.Created	data	Organization		L'entité organisation créée pour cet événement.
Organization.Data.Updated	data	Organization		L'entité organisation mise à jour pour cet événement.
Organization.Deleted	data	null	/
Organization.Membership.Updated	data	null	/

Événements OrganisationRôle (OrganizationRole)

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

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

Événement	Champ	Type	Optionnel	Remarques
OrganizationRole.Created	data	OrganizationRole		L'entité rôle d'organisation créée pour cet événement.
OrganizationRole.Data.Updated	data	OrganizationRole		L'entité rôle d'organisation mise à jour pour cet événement.
OrganizationRole.Deleted	data	null	/
OrganizationRole.Scope.Updated	data	null	/
OrganizationRole.Scope.Updated	organizationRoleId	string	✅	L'ID du rôle auquel les portées sont attribuées. (Disponible uniquement lorsque l'événement a été déclenché par la création d'un nouveau rôle avec des portées pré-attribuées)

Événements Permission d'organisation (OrganizationScope)

Événement	Champ	Type	Optionnel	Remarques
OrganizationScope.Created	data	OrganizationScope		L'entité portée d'organisation créée.
OrganizationScope.Data.Updated	data	OrganizationScope		L'entité portée d'organisation mise à jour.
OrganizationScope.Deleted	data	null	/

Corps de la requête des événements d'exception hook

Événements disponibles : Identifier.Lockout

Le corps de la requête est un objet JSON qui contient les champs standards du corps de la requête et des champs additionnels comme ci-dessous :

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

Champ	Type	Optionnel	Remarques
hookId	string		L'identifiant dans Logto.
event	string		L'événement qui déclenche ce hook.
createdAt	string		La date de création du payload au format ISO.
userAgent	string	✅	Le user-agent pour la requête.
ip	string	✅	L'adresse IP pour la requête.
interactionEvent	string	✅	L'événement d'interaction qui déclenche ce hook.
sessionId	string	✅	L'ID de session (et non l'ID d'interaction) pour cet événement, si applicable.
applicationId	string	✅	L'ID d'application associé à cet événement, si applicable.
application	ApplicationEntity	✅	Les informations de l'application associée à cet événement, si applicable.
type	SignInIdentifier		Le type d'identifiant utilisateur, ex : email, téléphone ou nom d'utilisateur.
value	string		La valeur de l'identifiant utilisateur qui a déclenché le verrouillage.