Webhooks de notification

Modifier en ligne

Les webhooks de notification constituent une fonction hautement polyvalente dans IBM® Verify. Ils permettent à un administrateur de configurer un noeud final pour recevoir en temps réel un ensemble sélectionné de données d'événement. Tout événement signalé dans Verify peut être propagé vers le webhook configuré, ce qui permet à Verify d'interagir avec des systèmes externes en fonction de l'événement.

Les utilisations courantes de cette fonction peuvent inclure les utilisations suivantes.

Suivi des tentatives de connexion d'un utilisateur
Conservation dans Cloud Directory des modifications apportées à un répertoire CRM externe ou un annuaire d'utilisateurs
Détection des nouveaux appareils MFA
Transfert d'événements à un SIEM

Pour plus d'informations sur les charges utiles des événements, consultez Types d'événements et charges utiles.

L'administrateur peut configurer un webhook de notification avec un ensemble d'intérêts. Cet ensemble décide des événements à envoyer depuis Verify au système externe.

Les webhooks de notification représentent un volume élevé. Sous charge, Verify publie un grand nombre d'événements. Le système externe doit être préparé à recevoir un niveau correspondant de charge. Des temps de réponse rapides provenant des noeuds finaux webhook configurés par l'administrateur sont essentiels lorsque des webhooks de notification sont utilisés dans les flux utilisateur.

Configuration

Voir la documentation d'API pour la structure complète des objets de configuration de webhook. Cette section se concentre sur la partie intérêts d'un webhook de notification.

Le fichier JSON de configuration du webhook contient une propriété notification. Cette propriété est un objet JSON imbriqué qui contient toutes les options de configuration spécifiques aux notifications. La propriété interests est définie dans cet objet notification. Lorsqu'un événement est émis, il est vérifié par rapport à chaque élément de la propriété interests. Si un élément de la propriété interests a pour résultat une correspondance, l'événement est envoyé à la destination du webhook. Les intérêts sont vérifiés dans l'ordre, donc dans les cas d'utilisation hautes performances, la mise en correspondance la plus large est la méthode la plus efficace.

Un intérêt se compose de deux zones, d'une name conviviale et d'une liste de clauses. Ces clauses déterminent si l'intérêt est une correspondance. Les clauses sont connectés à l'aide d'une opération AND, et l'intérêt est satisfait uniquement s'ils correspondent tous. Une clause se compose de trois zones :

key: Est utilisé pour déterminer l'emplacement dans l'événement à inspecter pour déterminer si cette clause correspond. Il doit s'agir d'un nom de propriété JSON. key peut être utilisé pour évaluer des clés ou des clés de niveau supérieur dans l'objet data d'un événement. Lorsqu'il fait référence à l'objet data, la notation JSON décimale est utilisée. Par exemple, data.action.
value: Value est la valeur attendue du pour la zone en cours d'inspection.
operation: Indique si une correspondance sur cette clause entraîne un événement included ou excluded.

Par exemple, dans un scénario où les événements d'authentification sont les principaux intérêts et que vous souhaitez filtrer les authentifications qui se produisent via la fédération, utilisez ces clauses.

Key: event_type, Value: authentication, Operation: include

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

Ces clauses deviennent l'évaluation logique.

event_type EST authentication ET data.subtype N'EST PAS federation

Exemples

Le code suivant est un exemple complet de la propriété notification dans une configuration de webhook destinée à répondre à divers scénarios.

Tous les événements d'authentification non fédérés

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

Détection de réexécution

La zone id d'un événement reste cohérente pour la durée de vie de cet événement. Indique s'il doit être dans un appel webhook ou dans les données d'événement extraites de l'API d'événements. Cette valeur id est également utilisée comme valeur dans l'en-tête X-Webhook-ID pour les webhooks de notification.

Lettres mortes de notification

Vous pouvez configurer un webhook pour enregistrer lorsqu'une notification n'a pas été distribuée au webhook.

Un administrateur peut synchroniser les distributions ayant échoué en utilisant l'API de lettres-mortes du webhook de notification, ainsi que l'API d'événements. Ces lettres mortes enregistrées contiennent l'ID de la notification non distribuée et l'heure de la notification. Pour afficher la notification non distribuée, un administrateur peut utiliser la valeur d'ID pour interroger directement l'API d'événements pour une valeur d'événement unique. Les horodatages de plusieurs événements peuvent être utilisés pour extraire une plage d'événements, puis utiliser les ID pour les filtrer sur le client.

Synchronisation des rebut

Il existe un mécanisme automatisé qui tente de redistribuer les lettres mortes au webhook configuré. Ces tentatives de synchronisation sont identifiables par la présence de la valeur "deadletter": true dans le contenu.

Vous pouvez déclencher une synchronisation de rebut de deux manières:

Manuellement, par un appel à l'API de vidage.
Automatiquement, lorsqu'un webhook de notification affiche un bon état de santé.
- Définissez la configuration pour spécifier la fréquence de cette synchronisation automatisée. Pour plus de détails, voir la documentation de l'API.
- L'API manuelle peut toujours être utilisée pour déclencher une synchronisation, quelle que soit la configuration.

Une API de statut peut être utilisée pour vérifier si un webhook exécute une synchronisation et la progression en cours de la synchronisation. Pour plus de détails, voir la documentation de l'API. Seul le résultat de l'exécution de la synchronisation est conservé par webhook. Ces résultats sont conservés pendant 7 jours ou jusqu'à ce qu'une autre synchronisation soit exécutée.

Si une tentative de redistribution d'une notification échoue lors de la synchronisation, la synchronisation est arrêtée. La limite de temps difficile pour les rapprochements est de 2 heures. Si toutes les lettres mortes ne sont pas vidées dans ce délai, d'autres synchronisations doivent être exécutées.