Webhooks 요청

유효한 훅 이벤트가 발생하면, Logto는 해당하는 웹훅을 찾아 각 훅 구성에 따라 POST 요청을 보냅니다.

요청 헤더

Key	Customizable	Notes
user-agent	✅	기본값은 Logto (https://logto.io/)입니다.
content-type	✅	기본값은 application/json입니다.
logto-signature-sha-256		요청 본문의 서명입니다. 웹훅 보안을 참조하세요.

동일한 키로 요청 헤더를 사용자 정의하여 사용자 정의 가능한 헤더를 덮어쓸 수 있습니다.

상호작용 훅 이벤트 요청 본문

사용 가능한 이벤트: 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;
};

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

Field	Type	Optional	Notes
hookId	string		Logto에서의 식별자입니다.
event	string		이 훅을 트리거하는 이벤트입니다.
createdAt	string		ISO 형식의 페이로드 생성 시간입니다.
interactionEvent	string		이 훅을 트리거하는 상호작용 이벤트입니다.
sessionId	string	✅	이 이벤트에 대한 세션 ID (상호작용 ID 아님)입니다, 해당하는 경우.
userAgent	string	✅	이 훅을 트리거하는 요청의 사용자 에이전트입니다.
userIp	string	✅	이 훅을 트리거하는 요청의 IP 주소입니다.
userId	string	✅	이 이벤트와 관련된 사용자 ID입니다, 해당하는 경우.
user	UserEntity	✅	이 이벤트와 관련된 사용자 엔티티입니다, 해당하는 경우.
applicationId	string	✅	이 이벤트와 관련된 애플리케이션 ID입니다, 해당하는 경우.
application	ApplicationEntity	✅	이 이벤트와 관련된 애플리케이션 정보입니다, 해당하는 경우.

자세한 필드 설명은 사용자 및 애플리케이션 참조를 확인하세요.

데이터 변이 훅 이벤트 요청 본문

표준 요청 본문 필드

Field	Type	Optional	Notes
hookId	string		Logto에서의 식별자입니다.
event	string		이 훅을 트리거하는 이벤트입니다.
createdAt	string		ISO 형식의 페이로드 생성 시간입니다.
userAgent	string	✅	요청의 사용자 에이전트입니다.
ip	string	✅	요청의 IP 주소입니다.

상호작용 API 컨텍스트 본문 필드

사용자 상호작용 API 호출에 의해 트리거되는 데이터 변이 훅 이벤트입니다.

사용 가능한 이벤트: User.Created, User.Data.Updated

Field	Type	Optional	Notes
interactionEvent	string	✅	이 훅을 트리거하는 상호작용 이벤트입니다.
sessionId	string	✅	이 이벤트에 대한 세션 ID (상호작용 ID 아님)입니다, 해당하는 경우.
applicationId	string	✅	이 이벤트와 관련된 애플리케이션 ID입니다, 해당하는 경우.
application	ApplicationEntity	✅	이 이벤트와 관련된 애플리케이션 정보입니다, 해당하는 경우.

Management API 컨텍스트 본문 필드

Management API 호출에 의해 트리거되는 데이터 변이 훅 이벤트입니다.

Field	Type	Optional	Notes
path	string	✅	이 훅을 트리거하는 API 호출의 경로입니다.
method	string	✅	이 훅을 트리거하는 API 호출의 메서드입니다.
status	number	✅	이 훅을 트리거하는 API 호출의 응답 상태 코드입니다.
params	object	✅	이 훅을 트리거하는 API 호출의 요청 koa 경로 매개변수입니다.
matchedRoute	string	✅	이 훅을 트리거하는 API 호출의 koa 매칭된 경로입니다. Logto는 이 필드를 사용하여 활성화된 훅 이벤트를 매칭합니다.

데이터 페이로드 본문 필드

사용자 이벤트

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	/

조직 역할 이벤트

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입니다. (사전 할당된 스코프로 새 역할을 생성할 때 이벤트가 트리거된 경우에만 사용 가능)

조직 권한 (조직 스코프) 이벤트

Event	Field	Type	Optional	Notes
OrganizationScope.Created	data	OrganizationScope		생성된 조직 스코프 엔티티입니다.
OrganizationScope.Data.Updated	data	OrganizationScope		업데이트된 조직 스코프 엔티티입니다.
OrganizationScope.Deleted	data	null	/