Benachrichtigungs-Webhooks

Online bearbeiten

Webhooks für Benachrichtigungen sind eine vielseitige Funktion in IBM® Verify. Sie ermöglichen es einem Administrator, einen Endpunkt für den Empfang einer ausgewählten Gruppe von Ereignisdaten in Echtzeit einzurichten. Jedes Ereignis, das in Verify ausgelöst wird, kann an den konfigurierten Webhook weitergegeben werden, wodurch Verify ereignisgesteuert mit externen Systemen interagieren kann.

Allgemeine Verwendungen dieser Funktion können die folgenden Verwendungen umfassen.

Anmeldeversuche für einen Benutzer verfolgen
Aktualisieren eines externen CRM- oder Benutzerverzeichnisses mit Änderungen in Cloud Directory
Neue MFA-Geräte erkennen
Ereignisse an SIEM weiterleiten

Informationen zu Ereignis-Payloads finden Sie unter „Ereignistypen und Payloads “.

Der Administrator kann einen Benachrichtigungs-Webhook mit einer Gruppe von Interessen konfigurieren. Diese Gruppe von Interessen entscheidet, welche Ereignisse von Verify an das externe System gesendet werden.

Benachrichtigungs-Webhooks haben ein hohes Volumen. Unter Last veröffentlicht Verify eine Vielzahl von Ereignissen. Das externe System muss darauf vorbereitet sein, eine entsprechende Last aufzunehmen. Schnelle Antwortzeiten von den vom Administrator konfigurierten Webhook-Endpunkten sind wichtig, wenn Benachrichtigungs-Webhooks in Benutzerabläufen verwendet werden.

Konfiguration

Informationen zur vollständigen Struktur des Webhook-Konfigurationsobjekts finden Sie in der API-Dokumentation. Dieser Abschnitt konzentriert sich auf den Interessenbereich eines Benachrichtigungs-Webhooks.

Die JSON-Konfigurationsdatei für Webhooks enthält eine notification-Eigenschaft. Diese Eigenschaft ist ein verschachteltes JSON-Objekt, das alle benachrichtigungsspezifischen Konfigurationsoptionen enthält. Die Eigenschaft interests ist in diesem notification-Objekt definiert. Wenn ein Ereignis ausgelöst wird, wird sie mit jedem Element in der Eigenschaft interests abgeglichen. Wenn ein Element in der Eigenschaft interests als Übereinstimmung ausgewertet wird, wird das Ereignis an das Webhook-Ziel gesendet. Die Interessen werden in der richtigen Reihenfolge geprüft. In Anwendungsfällen mit hoher Leistung ist die breiteste Übereinstimmung die effizienteste Methode.

Ein Interesse besteht aus zwei Feldern, einem freundlichen name und einer Liste von clauses. Diese Klauseln entscheiden, ob das Interesse übereinstimmt. Die clauses werden mit einer AND-Operation verknüpft, und nur wenn sie alle übereinstimmen, ist das Interesse erfüllt. Eine Klausel besteht aus drei Feldern:

key: Wird verwendet, um zu bestimmen, wo im Ereignis überprüft werden soll, ob diese Klausel übereinstimmt. Es muss ein JSON-Eigenschaftsname sein. key kann verwendet werden, um Schlüssel der höchsten Ebene oder Schlüssel im Objekt data eines Ereignisses auszuwerten. Wenn es auf das Objekt data verweist, wird die JSON-Punktschreibweise verwendet. Beispiel: data.action.
value: Value ist der erwartete Wert des zu überprüfenden Felds.
operation: Gibt an, ob eine Übereinstimmung mit dieser Klausel dazu führt, dass das Ereignis included oder excluded ist.

In einem Szenario, in dem Authentifizierungsereignisse im Mittelpunkt des Interesses stehen und Sie Authentifizierungen herausfiltern möchten, die über einen Verbund erfolgen, verwenden Sie beispielsweise diese Klauseln.

Key: event_type, Value: authentication, Operation: include

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

Diese Klauseln bilden die logische Auswertung.

event_type IS authentication AND data.subtype IS NOT federation

Beispiele

Der folgende Code ist ein vollständiges Beispiel für die Eigenschaft notification in einer Webhook-Konfiguration, um verschiedene Szenarien zu erfüllen.

Alle Authentifizierungsereignisse ohne Föderation

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

Wiedergabeerkennung

Das Feld id eines Ereignisses bleibt für die Lebensdauer dieses Ereignisses konsistent. Sei es in einem Webhook-Aufruf oder in den Ereignisdaten, die von der Ereignis-API abgerufen werden. Dieser id-Wert wird auch als Wert im Header X-Webhook-ID für Benachrichtigungs-Webhooks verwendet.

Benachrichtigung für nicht zustellbare Nachrichten

Sie können einen Webhook konfigurieren, um aufzuzeichnen, wenn eine Benachrichtigung nicht erfolgreich an den Webhook zugestellt werden konnte.

Ein Administrator kann die fehlgeschlagenen Zustellungen abgleichen, indem er die API für nicht zustellbare Nachrichten des Benachrichtigungs-Webhooks zusammen mit der Ereignis-API verwendet. Diese protokollierten unzustellbaren Nachrichten enthalten die ID der nicht zugestellten Benachrichtigung sowie den Zeitpunkt der Benachrichtigung. Um die Benachrichtigung über eine nicht zugestellte Nachricht anzuzeigen, kann ein Administrator anhand der ID-Nummer direkt einen einzelnen Ereigniswert über die Events-API abfragen. Anhand der Zeitstempel mehrerer Ereignisse lässt sich ein Ereignisbereich abrufen, der anschließend anhand der IDs auf dem Client gefiltert werden kann.

Abgleich nicht zugellieferter Sendungen

Es gibt einen automatisierten Mechanismus, der versucht, „Dead Letters“ erneut an den konfigurierten Webhook zu übermitteln. Diese Abgleichversuche lassen sich anhand des Vorhandenseins des Werts "deadletter": true in der Nutzlast erkennen.

Sie können die Dead-Letter-Abstimmung auf zwei verschiedene Arten auslösen:

Manuell durch einen Aufruf der Flush-API.
Automatisch, sobald ein Benachrichtigungs-Webhook einen einwandfreien Status anzeigt.
- Legen Sie in der Konfiguration fest, wie oft dieser automatische Abgleich stattfinden soll. Weitere Informationen finden Sie in der API-Dokumentation.
- Die manuelle API kann unabhängig von der Konfiguration weiterhin zum Auslösen einer Abstimmung verwendet werden.

Über eine Status-API lässt sich überprüfen, ob ein Webhook gerade eine Abgleichung durchführt, und der aktuelle Fortschritt der Abgleichung abfragen. Weitere Informationen finden Sie in der API-Dokumentation. Pro Webhook wird nur das Ergebnis der Abstimmung gespeichert. Diese Ergebnisse werden 7 Tage lang gespeichert oder bis eine weitere Abstimmung durchgeführt wird.

Schlägt der erneute Zustellversuch einer Benachrichtigung während des Abgleichs fehl, wird der Abgleich beendet. Die strikte Frist für die Abstimmung beträgt 2 Stunden. Werden nicht alle „Dead Letters“ innerhalb dieser Frist gelöscht, müssen weitere Abgleiche durchgeführt werden.