Webhooks リクエスト

有効なフックイベントが発生すると、Logto は対応する Webhook を検索し、各フック設定ごとに POST リクエストを送信します。

リクエストヘッダー

Key	カスタマイズ可	備考
user-agent	✅	デフォルトは Logto (https://logto.io/) です。
content-type	✅	デフォルトは application/json です。
logto-signature-sha-256		リクエストボディの署名。 Webhook のセキュリティ保護 を参照してください。

カスタマイズ可能なヘッダーは、同じキーで リクエストヘッダーのカスタマイズ により上書きできます。

インタラクションフックイベントのリクエストボディ

利用可能なイベント: PostRegister, PostSignIn, PostResetPassword

リクエストボディは、3 種類のデータフィールドを含む 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;
};

フィールド	型	オプション	備考
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	✅	このイベントに関連するアプリケーション情報。

各フィールドの詳細な説明は ユーザー および アプリケーション リファレンスを参照してください。

データ変更フックイベントのリクエストボディ

標準リクエストボディフィールド

フィールド	型	オプション	備考
hookId	string		Logto 内の識別子。
event	string		このフックをトリガーしたイベント。
createdAt	string		ペイロードの作成時刻（ISO 形式）。
userAgent	string	✅	リクエストのユーザーエージェント。
ip	string	✅	リクエストの IP アドレス。

インタラクション API コンテキストボディフィールド

ユーザーのインタラクション API コールによってトリガーされるデータ変更フックイベント。

利用可能なイベント: User.Created, User.Data.Updated

フィールド	型	オプション	備考
interactionEvent	string	✅	このフックをトリガーしたインタラクションイベント。
sessionId	string	✅	このイベントのセッション ID（インタラクション ID ではありません）。
applicationId	string	✅	このイベントに関連するアプリケーション ID。
application	ApplicationEntity	✅	このイベントに関連するアプリケーション情報。

Management API コンテキストボディフィールド

Management API コールによってトリガーされるデータ変更フックイベント。

フィールド	型	オプション	備考
path	string	✅	このフックをトリガーした API コールのパス。
method	string	✅	このフックをトリガーした API コールのメソッド。
status	number	✅	このフックをトリガーした API コールのレスポンスステータスコード。
params	object	✅	このフックをトリガーした API コールの koa パスパラメータ。
matchedRoute	string	✅	このフックをトリガーした API コールの koa マッチルート。Logto はこのフィールドで有効なフックイベントを判定します。

データペイロードボディフィールド

ユーザーイベント

イベント	フィールド	型	オプション	備考
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;
};

イベント	フィールド	型	オプション	備考
Role.Created	data	Role		このイベントで作成されたロール情報。
Role.Data.Updated	data	Role		このイベントで更新されたロール情報。
Role.Deleted	data	null
Role.Scope.Updated	data	Scope[]		ロールに割り当てられた更新済みスコープ。
Role.Scope.Updated	roleId	string	✅	スコープが割り当てられたロール ID。（事前割り当てスコープ付き新規ロール作成時のみ利用可能）

権限（スコープ）イベント

イベント	フィールド	型	オプション	備考
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;
};

イベント	フィールド	型	オプション	備考
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;
};

イベント	フィールド	型	オプション	備考
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）イベント

イベント	フィールド	型	オプション	備考
OrganizationScope.Created	data	OrganizationScope		作成された組織スコープ情報。
OrganizationScope.Data.Updated	data	OrganizationScope		更新された組織スコープ情報。
OrganizationScope.Deleted	data	null	/

例外フックイベントのリクエストボディ

利用可能なイベント: Identifier.Lockout

リクエストボディは、標準リクエストボディフィールドと以下の追加フィールドを含む JSON オブジェクトです：

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

フィールド	型	オプション	備考
hookId	string		Logto 内の識別子。
event	string		このフックをトリガーしたイベント。
createdAt	string		ペイロードの作成時刻（ISO 形式）。
userAgent	string	✅	リクエストのユーザーエージェント。
ip	string	✅	リクエストの IP アドレス。
interactionEvent	string	✅	このフックをトリガーしたインタラクションイベント。
sessionId	string	✅	このイベントのセッション ID（インタラクション ID ではありません）。
applicationId	string	✅	このイベントに関連するアプリケーション ID。
application	ApplicationEntity	✅	このイベントに関連するアプリケーション情報。
type	SignInIdentifier		ユーザーの識別子タイプ（例：email、phone、username）。
value	string		ロックアウトを引き起こしたユーザーの識別子値。