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

enum ApplicationType {
  Native = 'Native',
  SPA = 'SPA',
  Traditional = 'Traditional',
  MachineToMachine = 'MachineToMachine',
  Protected = 'Protected',
  SAML = 'SAML',
}

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

Field	Type	Optional	Notes
hookId	string		Logto의 식별자입니다.
event	string		이 hook을 트리거한 이벤트입니다.
createdAt	string		페이로드 생성 시간 (ISO 형식)입니다.
interactionEvent	string		이 hook을 트리거한 상호작용 이벤트입니다.
sessionId	string	✅	이 이벤트의 세션 ID (Interaction 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 (Interaction ID 아님), 해당되는 경우.
applicationId	string	✅	이 이벤트와 관련된 애플리케이션 ID, 해당되는 경우.
application	ApplicationEntity	✅	이 이벤트와 관련된 애플리케이션 정보, 해당되는 경우.

Management API 컨텍스트 본문 필드

Management API 호출로 트리거되는 데이터 변이 hook 이벤트입니다.

Field	Type	Optional	Notes
path	string	✅	이 hook을 트리거한 API 호출의 경로입니다.
method	string	✅	이 hook을 트리거한 API 호출의 메서드입니다.
status	number	✅	이 hook을 트리거한 API 호출의 응답 상태 코드입니다.
params	object	✅	이 hook을 트리거한 API 호출의 koa path params입니다.
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입니다. (사전 할당된 스코프로 새 역할 생성 시에만 제공)

권한(스코프) 이벤트

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	/

OrganizationRole 이벤트

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	/

예외 hook 이벤트 요청 본문

사용 가능한 이벤트: Identifier.Lockout

요청 본문은 표준 요청 본문 필드와 아래의 추가 필드를 포함하는 JSON 객체입니다:

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

Field	Type	Optional	Notes
hookId	string		Logto의 식별자입니다.
event	string		이 hook을 트리거한 이벤트입니다.
createdAt	string		페이로드 생성 시간 (ISO 형식)입니다.
userAgent	string	✅	요청의 user-agent입니다.
ip	string	✅	요청의 IP 주소입니다.
interactionEvent	string	✅	이 hook을 트리거한 상호작용 이벤트입니다.
sessionId	string	✅	이 이벤트의 세션 ID (Interaction ID 아님), 해당되는 경우.
applicationId	string	✅	이 이벤트와 관련된 애플리케이션 ID, 해당되는 경우.
application	ApplicationEntity	✅	이 이벤트와 관련된 애플리케이션 정보, 해당되는 경우.
type	SignInIdentifier		사용자의 식별자 유형 (예: email, phone, username).
value	string		잠금이 발생한 사용자의 식별자 값입니다.