メインコンテンツまでスキップ

Webhook の設定

Logto コンソールで Webhook を設定することで、シームレスな統合とリアルタイムのイベント通知をアプリケーションで受け取ることができます。簡単な設定、高度なセキュリティ、便利なヘルスモニタリング機能を利用できます。

Webhook を作成する​

まず、Logto Agent から呼び出される Webhook エンドポイントを作成します。このエンドポイントはサーバー上で実装し、HTTP リクエストを受信できる必要があります。

Logto コンソールで新しい Webhook を作成するには、次の手順に従ってください：

  1. Webhook の作成：コンソール > Webhook に移動し、「Webhook を作成」ボタンをクリックします。

  2. 名前：Webhook の名前を入力します。これは利用シーンを定義するための参照用です。

  3. エンドポイント URL：Endpoint URL を入力します。これはイベント発生時に Webhook の POST リクエストを受信するサーバーの URL です。セキュリティ上、URL は HTTPS で公開アクセス可能でなければならず、ローカルホストの URL は使用できません。

    注記:

    サーバーは Logto からの Webhook リクエストを受信した直後に、HTTP 200（"OK"）レスポンスで応答する必要があります。これにより、リクエストが受信されたことを通知します。

    対応する Webhook イベントのロジック処理が完了するまで応答を待つと、Webhook がタイムアウトする可能性があります。

    Logto Webhook には 200 以外のレスポンスを返さないでください。イベント処理中にエラーが発生した場合は、自身のサーバー側で処理してください。

  4. イベント：表示されるモーダルで、この Webhook をトリガーする イベント を選択します。サーバーへの負荷を避けるため、要件を満たす最小限のイベント数を選択することを推奨します。Webhook 作成後も、選択したイベントはいつでも変更できます。

    Webhook の作成

  5. 無効化 / 再有効化：デフォルトでは、Webhook は作成直後に有効化されます。一時的に Webhook を停止したい場合は、作成後にヘッダー右上の「三点リーダー」メニューから無効化または再有効化できます。

Webhook のセキュリティ対策​

サーバーが Webhook リクエストを受信できるようになったら、安全にリクエストを処理できるようにしましょう。Logto は各 Webhook リクエストのペイロードに署名を生成し、そのリクエストが Logto から送信されたことを検証できます。

新しい Webhook を作成した後、セキュリティを強化するためのオプションがあります：

  • 署名キー：Logto は各 Webhook ごとに一意のハッシュ署名（Signing Key）を生成します。このキーをリクエストヘッダーとしてエンドポイント実装に含めることができます。署名キーを検証することで、Webhook ペイロードが Logto から送信され、改ざんされていないことを確認できます。詳細は Webhook のセキュリティ対策 をご覧ください。
  • カスタムヘッダー：Webhook ペイロードにカスタムヘッダーを追加して、追加のコンテキストやメタデータを提供できます。この機能により、Webhook データの処理を効果的にサポートする関連情報を付加できます。

署名キーの活用とカスタムヘッダーの追加を検討することで、Webhook のセキュリティを強化し、受信したペイロードの完全性と真正性を確保できます。

Webhook のテスト​

Logto とサービス間の接続をテストするには、「テストペイロードを送信」ボタンをクリックするだけです。Logto は選択した各イベントのサンプルペイロードをエンドポイント URL に送信します。これらのテストリクエストには匿名データが含まれており、直近のリクエスト履歴には記録されません。

このテストにより、Webhook が Logto からのペイロードを正しく受信・処理できるように設定されているかを確認できます。本番環境で Webhook を運用する前に、統合を検証できます。

Webhook のヘルスステータス監視​

Logto では、Webhook のヘルスステータスを簡単に監視し、詳細な問題調査ができるツールを提供しています：

  • ヘルスステータス
    Logto の Webhook 一覧では、各 Webhook のヘルスステータス（過去 24 時間の成功率とリクエスト総数）が表示されます。この情報により、Webhook のパフォーマンスを把握できます。
  • 個別リクエストログ
    各 Webhook の「最近のリクエスト」セクションでは、過去 24 時間分のリクエストログにアクセスできます。各リクエストが個別に記録されており、詳細を確認したり、エラーや異常を調査できます。
  • 自動リトライ
    配信失敗（Webhook レスポンスステータスが 500 以上）の場合、Logto は自動的に最大 3 回まで再配信を試みます。同じリクエストの複数回のリトライでも、ログエントリは 1 つだけ生成され、不要な重複を防ぎます。すべてのリトライには同じ deliveryId がペイロードに含まれるため、すでに処理済みの配信をスキップ できます。

これらの監視機能を活用することで、Webhook のヘルスを効果的に追跡し、リクエストログを調査し、Webhook 統合の信頼性とパフォーマンスを確保できます。