通知 Webhook

オンラインで編集

通知 Webhook は、IBM® Verify において非常に汎用性の高い機能です。管理者は、選択した一連のイベント・データをリアルタイムで受信するようにエンドポイントをセットアップできます。 Verify で発生したすべてのイベントは、構成済みの Webhook に伝搬できます。これにより、Verify はイベント・ドリブン方式で外部システムと対話できるようになります。

この機能の一般的な使用方法として、以下のようなものがあります。

ユーザーのログイン試行のトラッキング
クラウド・ディレクトリーの変更に応じて、外部 CRM またはユーザー・ディレクトリーを最新の状態に維持
新規 MFA デバイスの検出
SIEM へのイベントの転送

イベントのペイロードに関する詳細については、「イベントの種類とペイロード」を参照してください。

管理者は、関心事項のセットに合わせて通知 Webhook を構成できます。この関心事項のセットによって、Verify から外部システムに送信されるイベントが決まります。

通知 Webhook は大容量です。負荷がかかっている場合、Verify は多数のイベントをパブリッシュします。外部システムは、同等レベルの負荷を受け取れるように準備ができている必要があります。通知 Webhook がユーザー・フローで使用される場合は、管理者が構成した Webhook エンドポイントからの応答が迅速であることが重要です。

構成

Webhook 構成オブジェクト構造の詳細については、API の資料を参照してください。このセクションでは、通知 Webhook での関心事項の部分に焦点を当てて説明します。

Webhook 構成 JSON ファイルには、notification プロパティーが含まれています。このプロパティーはネストされた JSON オブジェクトで、通知固有の構成オプションをすべて含んでいます。 interests プロパティーは、この notification オブジェクト内で定義されます。イベントが発生すると、interests プロパティー内の各エレメントに対してイベントが検査されます。 interests プロパティー内のいずれかのエレメントが一致と評価されると、イベントは Webhook 宛先に送信されます。関心事項は順番にチェックされるため、高性能なユース・ケースでは、最も一般的に一致するものを先頭に置くことが最も効率的な方法です。

関心事項は 2 つのフィールド (分かりやすいname と clauses のリスト) で構成されます。これらの節によって、関心事項が一致であるかどうかが決定されます。 clauses は AND 演算で結合され、それらがすべて一致する場合にのみ関心事項は満たされます。節は、以下の 3 つのフィールドで構成されます。

key: この節が一致するかどうかを検出するために、イベントのどこを検査するかを決定するために使用されます。これは JSON プロパティー名でなければなりません。 key を使用して、イベントの data オブジェクト内の最上位キーまたはキーを評価できます。 data オブジェクトを参照する場合は、JSON ドット表記が使用されます。例えば、data.actionなどです。
value: Value は、検査対象のフィールドの予期される値です。
operation: この節での一致により、イベントが included となるか excluded となるかを示します。

例えば、認証イベントが重要な関心事項である場合に、連携によって発生する認証をフィルターで除外するには、以下の節を使用します。

Key: event_type, Value: authentication, Operation: include

Key: data.subtype, Value: federation, Operation: exclude

これらの節は論理評価になります。

event_type IS authentication AND data.subtype IS NOT federation

例

以下のコードは、さまざまなシナリオを満たすための、Webhook 構成内の notification プロパティーの完全な例です。

すべての非連携認証イベント

"notifications": {
    "interests": [
      {
        "name": "Non-federation authentication events",
        "clauses": [
          {
            "key": "event_type",
            "value": "authentication",
            "operation": "include"
          },
          {
            "key": "data.subtype",
            "value": "federation",
            "operation": "exclude"
          }
        ]
      }
    ]
  }

リプレイの検出

イベントの id フィールドは、そのイベントの存続期間中は一貫して維持されます。 Webhook コールアウトにあっても、イベント API から取得されるイベント・データにあっても同様です。この id 値は、通知 Webhook の X-Webhook-ID ヘッダーの値としても使用されます。

通知デッド・レター

通知が Webhook に正常に配信されなかった場合に記録するように Webhook を構成できます。

管理者は、通知 Webhook のデッド・レター API とイベント API を併用して、失敗した配信を調整できます。これらの記録された未達通知には、配信されなかった通知のIDと通知時刻が含まれています。配信されなかった通知を確認するには、管理者はID値を使用して、イベントAPIに対して個別のイベント値を直接照会することができます。複数のイベントのタイムスタンプを使用してイベントの範囲を取得し、そのIDを用いてクライアント側でフィルタリングを行うことができます。

未配達郵便物の照合

設定されたWebhookに対して、配信不能となったメッセージの再配信を試みる自動メカニズムが用意されています。これらの照合の試みは、ペイロード内に値 "deadletter": true が存在することで識別できます。

デッドレターの照合は、次の2つの方法のいずれかで実行できます：

flush API を呼び出すことで、手動で実行します。
通知Webhookが正常な状態を示している場合、自動的に。
- この自動照合がどのくらいの頻度で行われるかを指定するように設定してください。詳細については、APIドキュメントを参照してください。
- 設定に関わらず、手動APIを使用して照合を実行することは可能です。

ステータスAPIを使用すると、Webhookがレコンサイレメントを実行中かどうか、およびレコンサイレメントの現在の進行状況を確認できます。詳細については、APIドキュメントを参照してください。 Webhookごとに、照合の実行結果のみが保持されます。これらの結果は、7日間、または次の照合が実行されるまで保持されます。

照合中に通知の再配信が失敗した場合、その照合は終了します。照合の厳格な時間制限は2時間です。その時間内にすべてのデッドレターがすべて削除されない場合は、さらに照合作業を実行する必要があります。