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 つの Webhook を有効化する例を示します：
よくある質問
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 でフィーチャーリクエストを作成するか、お問い合わせください。