Webhook
Logto の Webhook は、ユーザーアカウント、ロール、権限、組織 (Organizations)、組織ロール、組織権限、ユーザーインタラクション など、さまざまなイベントに対してリアルタイム通知を提供します。
イベントがトリガーされると、Logto は指定したエンドポイント URL に非同期で HTTP リクエストを送信します。このリクエストには、ユーザー、アプリケーション、リクエストコンテキストなど、イベントの詳細が含まれます。ペイロードやヘッダーの詳細は Webhook リクエスト を参照してください。
Webhook の配信は認証リクエストの外で行われ、現在のフローの結果を変更することはできません。サインインが継続する前に必ず完了させる必要がある同期コードには、Actions を利用してください。
ユーザーのニーズに応じて、対応イベントを随時追加しています。ビジネス要件があれば、ぜひご連絡ください。
なぜ Webhook を使うのか？
Webhook はアプリケーション間のリアルタイム通信を提供し、ポーリングの必要をなくし、即時のデータ更新を可能にします。複雑なコードや独自 API なしで、アプリケーション統合やワークフロー自動化を簡素化します。
CIAM における一般的な Webhook のユースケース例：
- メール送信：Webhook を設定して、新規ユーザー登録時にウェルカムメールを送信したり、ユーザーが新しいデバイスや場所からサインインした際に管理者へ通知したりできます。
- 通知送信：Webhook を設定して、CRM システムと連携したバーチャルアシスタントをトリガーし、ユーザー登録時にリアルタイムでカスタマーサポートを提供できます。
- 追加の API コール実行：Webhook を設定して、ユーザーのメールドメインや IP アドレスを確認し、Logto Management API を使ってリソース権限付きの適切なロールを割り当てることができます。
- データ同期：Webhook を設定して、ユーザーアカウントの停止や削除などの変更をアプリケーションに反映させることができます。
- レポート生成：Webhook を設定してユーザーのログインアクティビティデータを受信し、ユーザーエンゲージメントや利用パターンのレポート作成に活用できます。
用語
| 項目 | 説明 |
|---|---|
| Webhook イベント | Logto が配信可能なサポートイベントタイプ。例：PostSignIn や User.Created など。 |
| Webhook | 1 つ以上のイベントを購読し、そのペイロードを HTTP エンドポイントへ送信する設定。 |
たとえば、ユーザーがサインインした後にセキュリティサービスへ通知したい場合は、PostSignIn を購読する Webhook を作成します。
Logto で PostSignIn イベントに対して 2 つの Webhook を有効化する例：
よくある質問
Webhook で同期的な認証 (Authentication) 判定はできますか？
できません。Webhook は非同期通知のため、そのレスポンスで現在の認証 (Authentication) フローを許可・ブロック・変更することはできません。
サインイン継続前に Logto でカスタムコード実行や外部 API コール、ユーザー更新が必要な場合は Actions を利用してください。Actions は同期的に動作するため、外部依存先は高速かつ信頼性の高いものにしてください。
ユーザー権限変更への対応方法は？
ユーザー権限変更の管理 ガイドを参照してください。
Webhook タイムアウトのデバッグ方法は？
Webhook を受信するエンドポイントは、できるだけ早く 2xx レスポンスを返して Logto に Webhook の受信成功を伝える必要があります。Webhook の処理ロジックが複雑すぎると数秒かかり、Logto Webhook がタイムアウトする場合があります。ベストプラクティスは独自のイベントキューを用意し、Logto Webhook 受信時にイベントをキューへ挿入し、すぐに 2xx レスポンスを返すことです。その後、独自のワーカーでキュー内のタスクを順次処理してください。ワーカーでエラーが発生した場合は、自サーバー側で対応してください。
PostSignIn Webhook からクライアント IP アドレスを取得できますか？
PostSignIn Webhook からクライアント IP アドレスを取得できますか？はい、Webhook のペイロードで IP アドレスやユーザーエージェントなどを取得できます。現在サポートされていない情報が必要な場合は、GitHub issues でフィーチャーリクエストを作成するか、お問い合わせください。