Requisição de Webhooks

Uma vez que um evento de hook válido é emitido, o Logto encontrará os webhooks correspondentes e enviará uma requisição POST por configuração de hook.

Cabeçalhos da requisição

Chave	Personalizável	Observações
user-agent	✅	Logto (https://logto.io/) por padrão.
content-type	✅	application/json por padrão.
logto-signature-sha-256		a assinatura do corpo da requisição, consulte protegendo seus webhooks.

Você pode sobrescrever cabeçalhos personalizáveis personalizando os cabeçalhos da requisição com a mesma chave.

Corpo da requisição de eventos de interaction hook

Eventos disponíveis: PostRegister, PostSignIn, PostResetPassword

O corpo da requisição é um objeto JSON que contém três tipos de campo de dados:

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	Observações
hookId	string		O identificador no Logto.
event	string		Qual evento disparou este hook.
createdAt	string		O horário de criação do payload em formato ISO.
interactionEvent	string		O evento de interação que disparou este hook.
sessionId	string	✅	O ID da sessão (não o ID de interação) para este evento, se aplicável.
userAgent	string	✅	O user-agent da requisição que disparou este hook.
userIp	string	✅	O endereço IP da requisição que disparou este hook.
userId	string	✅	O ID do usuário relacionado a este evento, se aplicável.
user	UserEntity	✅	A entidade de usuário relacionada a este evento, se aplicável.
applicationId	string	✅	O ID do aplicativo relacionado a este evento, se aplicável.
application	ApplicationEntity	✅	As informações do aplicativo relacionado a este evento, se aplicável.

Veja as referências de Usuários e Aplicativos para explicações detalhadas dos campos.

Corpo da requisição de eventos de data mutation hook

Campos padrão do corpo da requisição

Campo	Tipo	Opcional	Observações
hookId	string		O identificador no Logto.
event	string		Qual evento disparou este hook.
createdAt	string		O horário de criação do payload em formato ISO.
userAgent	string	✅	O user-agent da requisição.
ip	string	✅	O endereço IP da requisição.

Campos de contexto de Interaction API no corpo

Eventos de data mutation hook disparados por chamadas de API de interação do usuário.

Eventos disponíveis: User.Created, User.Data.Updated

Campo	Tipo	Opcional	Observações
interactionEvent	string	✅	O evento de interação que disparou este hook.
sessionId	string	✅	O ID da sessão (não o ID de interação) para este evento, se aplicável.
applicationId	string	✅	O ID do aplicativo relacionado a este evento, se aplicável.
application	ApplicationEntity	✅	As informações do aplicativo relacionado a este evento, se aplicável.

Campos de contexto de Management API no corpo

Eventos de data mutation hook disparados por chamadas de Management API.

Campo	Tipo	Opcional	Observações
path	string	✅	O caminho da chamada de API que disparou este hook.
method	string	✅	O método da chamada de API que disparou este hook.
status	number	✅	O código de status da resposta da chamada de API que disparou este hook.
params	object	✅	Os parâmetros de caminho koa da chamada de API que disparou este hook.
matchedRoute	string	✅	A rota koa correspondente da chamada de API que disparou este hook. O Logto usa este campo para corresponder eventos habilitados.

Campos de payload de dados no corpo

Eventos de usuário

Evento	Campo	Tipo	Opcional	Observações
User.Created	data	UserEntity		A entidade de usuário criada para este evento.
User.Data.Updated	data	UserEntity		A entidade de usuário atualizada para este evento.
User.Deleted	data	null	/

Eventos de papel (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	Observações
Role.Created	data	Role		A entidade de papel criada para este evento.
Role.Data.Updated	data	Role		A entidade de papel atualizada para este evento.
Role.Deleted	data	null
Role.Scope.Updated	data	Scope[]		Os escopos atualizados atribuídos ao papel.
Role.Scope.Updated	roleId	string	✅	O ID do papel ao qual os escopos estão atribuídos. (Disponível apenas quando o evento foi disparado por criação de novo papel com escopos pré-atribuídos)

Eventos de permissão (Scope)

Evento	Campo	Tipo	Opcional	Observações
Scope.Created	data	Scope		A entidade de escopo criada para este evento.
Scope.Data.Updated	data	Scope		A entidade de escopo atualizada para este evento.
Scope.Deleted	data	null	/

Eventos de organização (Organization)

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

Evento	Campo	Tipo	Opcional	Observações
Organization.Created	data	Organization		A entidade de organização criada para este evento.
Organization.Data.Updated	data	Organization		A entidade de organização atualizada 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	Observações
OrganizationRole.Created	data	OrganizationRole		A entidade de papel de organização criada para este evento.
OrganizationRole.Data.Updated	data	OrganizationRole		A entidade de papel de organização atualizada para este evento.
OrganizationRole.Deleted	data	null	/
OrganizationRole.Scope.Updated	data	null	/
OrganizationRole.Scope.Updated	organizationRoleId	string	✅	O ID do papel ao qual os escopos estão atribuídos. (Disponível apenas quando o evento foi disparado por criação de novo papel com escopos pré-atribuídos)

Eventos de permissão de organização (OrganizationScope)

Evento	Campo	Tipo	Opcional	Observações
OrganizationScope.Created	data	OrganizationScope		A entidade de escopo de organização criada.
OrganizationScope.Data.Updated	data	OrganizationScope		A entidade de escopo de organização atualizada.
OrganizationScope.Deleted	data	null	/

Corpo da requisição de eventos de exception hook

Eventos disponíveis: Identifier.Lockout

O corpo da requisição é um objeto JSON que contém os campos padrão do corpo da requisição e campos adicionais conforme abaixo:

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

Campo	Tipo	Opcional	Observações
hookId	string		O identificador no Logto.
event	string		Qual evento disparou este hook.
createdAt	string		O horário de criação do payload em formato ISO.
userAgent	string	✅	O user-agent da requisição.
ip	string	✅	O endereço IP da requisição.
interactionEvent	string	✅	O evento de interação que disparou este hook.
sessionId	string	✅	O ID da sessão (não o ID de interação) para este evento, se aplicável.
applicationId	string	✅	O ID do aplicativo relacionado a este evento, se aplicável.
application	ApplicationEntity	✅	As informações do aplicativo relacionado a este evento, se aplicável.
type	SignInIdentifier		O tipo de identificador do usuário, por exemplo, email, telefone ou nome de usuário.
value	string		O valor do identificador do usuário que disparou o bloqueio.