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 données utiles des événements, consultez la section « Types d'événements et données 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 messages non remis enregistrés contiennent l'identifiant de la notification non remise ainsi que l'heure de cette notification. Pour consulter la notification non remise, un administrateur peut utiliser la valeur d'identifiant pour interroger directement l'API des événements et obtenir la valeur d'un événement spécifique. Les horodatages de plusieurs événements peuvent être utilisés pour récupérer une série d'événements, puis pour les filtrer côté client à l'aide de leurs identifiants.

Rapprochement des messages non remis

Il existe un mécanisme automatisé qui tente de renvoyer les messages non remis vers le webhook configuré. Ces tentatives de réconciliation sont identifiables par la présence de la valeur "deadletter": true dans la charge utile.

Vous pouvez lancer le traitement des messages non remis de deux façons différentes :

Manuellement, en appelant l'API `flush`.
Automatiquement, lorsqu'un webhook de notification indique que tout fonctionne correctement.
- Définissez les paramètres de configuration pour déterminer la fréquence à laquelle ce rapprochement automatique doit avoir lieu. Pour plus de détails, consultez la documentation de l'API.
- L'API manuelle peut toujours être utilisée pour lancer un rapprochement, quelle que soit la configuration.

Une API d'état permet de vérifier si un webhook est en train d'effectuer une réconciliation et de connaître l'état d'avancement de celle-ci. Pour plus de détails, consultez la documentation de l'API. Seul le résultat de l'exécution du rapprochement est conservé pour chaque webhook. Ces résultats sont conservés pendant 7 jours ou jusqu'à ce qu'un nouveau rapprochement soit effectué.

Si une tentative de réexpédition d'une notification échoue lors du rapprochement, celui-ci est interrompu. Le délai strict pour les rapprochements est de 2 heures. Si toutes les lettres mortes ne sont pas supprimées dans ce délai, il faudra effectuer d'autres opérations de rapprochement.