Webhook（ウェブフック）
Logto の Webhook は、ユーザーアカウント、ロール、権限、組織 (Organizations)、組織ロール、組織権限、ユーザーインタラクション など、さまざまなイベントに対してリアルタイム通知を提供します。
イベントがトリガーされると、Logto は指定したエンドポイント URL に HTTP リクエストを送信し、ユーザー ID、ユーザー名、メールアドレスなど、イベントに関する詳細情報を含みます（ペイロードやヘッダーに含まれるデータの詳細については Webhook リクエスト を参照してください）。アプリケーション側でこのリクエストを処理し、メール送信やデータベースの更新など、カスタマイズしたアクションを実行できます。
ユーザーのニーズに応じて、対応イベントを随時追加しています。ビジネスに特有の要件があれば、ぜひご連絡ください。
なぜ Webhook を使うのか？
Webhook はアプリケーション間のリアルタイム通信を実現し、ポーリングの必要をなくし、即時のデータ更新を可能にします。複雑なコードや独自 API なしで、アプリケーション統合やワークフロー自動化をシンプルにします。
CIAM における一般的な Webhook のユースケース例をいくつか紹介します：
- メール送信：Webhook を設定し、新規ユーザー登録時にウェルカムメールを送信したり、新しいデバイスや場所からサインインがあった際に管理者へ通知したりできます。
- 通知送信：Webhook を設定し、CRM システムのバーチャルアシスタントをトリガーして、ユーザー登録時にリアルタイムでカスタマーサポートを提供できます。
- 追加の API コール実行：Webhook を設定し、ユーザーのメールドメインや IP アドレスをチェックしてアクセスを検証し、その後 Logto Management API を使ってリソース権限付きの適切なロールを割り当てます。
- データ同期：Webhook を設定し、ユーザーアカウントの停止や削除などの変更をアプリケーション側で常に最新に保ちます。
- レポート生成：Webhook を設定し、ユーザーのログインアクティビティデータを受け取り、ユーザーエンゲージメントや利用パターンのレポート作成に活用します。
用語
| Item | Description |
|---|---|
| Event | 特定のアクションが実行されると、特定タイプのフックイベントがトリガーされます。例：ユーザーがサインアップを完了し新しいアカウントを作成した際、Logto は PostRegister フックイベントを発行します。 |
| Hook | 特定イベントにフックする 1 つまたは複数のアクション。アクションには API コールやコードスニペットの実行などが含まれます。 |
| Webhook | イベントペイロードを使って API を呼び出すことを示すフックのサブタイプです。 |
| たとえば、開発者がユーザーが新しいデバイスからサインインした際に通知を送りたい場合、PostSignIn イベントに対して自身のセキュリティサービス API を呼び出す webhook を追加できます。 |
以下は、Logto で PostSignIn イベントに対して 2 つのウェブフックを有効化する例です：
よくある質問
Logto は同期 Webhook をサポートしていますか？
同期 Webhook を利用するとユーザーのサインインフローがよりスムーズになりますが、現時点では未対応です（将来的に対応予定です）。そのため、同期 Webhook に依存するシナリオは現状すべて異なる回避策が必要です。ご質問があればお気軽にご連絡ください。
ユーザー権限の変更にはどう対応すればよいですか？
ユーザー権限変更の管理 ガイドを参照してください。
Webhook のタイムアウトをデバッグするには？
Webhook を受信するエンドポイントは、Webhook を正常に受信したことを Logto に伝えるため、できるだけ早く 2xx レスポンスを返す必要があります。Webhook の処理ロジックはユーザーごとに大きく異なるため、処理が複雑すぎると数秒かかり、Logto Webhook がタイムアウトする場合があります。ベストプラクティスは独自のイベントキューを用意し、Logto Webhook を受信したらイベントをキューに挿入し、すぐに 2xx レスポンスを Logto に返すことです。その後、独自のワーカーでキュー内のタスクを順次処理します。ワーカーでエラーが発生した場合は、自身のサーバーで対応してください。
PostSignIn Webhook からクライアント IP アドレスを取得できますか？
PostSignIn Webhook からクライアント IP アドレスを取得できますか？はい、Webhook のペイロードで IP アドレスやユーザーエージェントなどを取得できます。現在サポートされていない情報が必要な場合は、GitHub issue でフィーチャーリクエストを作成するか、お問い合わせください。