通知 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 つの方法のいずれかでトリガーできます。

手動で、フラッシュ API を呼び出すことによって。
通知 Webhook が良好な正常性状況を示している場合は、自動的に表示されます。
- 構成を設定して、この自動調整が行われる頻度を指定します。詳しくは、API の資料を参照してください。
- 手動 API は、構成に関係なく、調整をトリガーするために引き続き使用できます。

状況 API を使用して、Webhook が調整を実行しているかどうか、および調整の現在の進行状況を確認できます。詳しくは、API の資料を参照してください。調整の実行結果のみが Web フックごとに保持されます。これらの結果は、7 日間、または別の調整が実行されるまで保持されます。

調整中に通知の再配信の試行が失敗した場合、調整は終了します。調整のハード・タイム・リミットは 2 時間です。その時間内にすべてのデッド・レターがフラッシュされない場合は、さらに調整を実行する必要があります。