Webhooks

Utilisez des webhooks pour recevoir des notifications à propos d'événements qui se produisent dans AppScan 360°.

Présentation

Les rappels HTTP définis par l'utilisateur (webhooks) sont pris en charge via l'API REST AppScan 360°. Les webhooks vous avertissent lorsque des événements se produisent dans AppScan 360°. Les types d'événements suivants sont pris en charge :

  • Exécution d'examen terminée
  • Compteurs d'application ou statut modifié

Pour utiliser les webhooks, commencez par télécharger et installer AppScan Presence sur votre réseau local (il s'agit généralement d'un processus unique). Presence se connecte à AppScan 360°.

Lorsqu'un webhook est déclenché, Presence reçoit une commande de la part d'AppScan 360° et envoie une requête HTTP GET à l'URI du webhook sur votre réseau local.

Etant donné que Presence envoie la requête depuis votre réseau, vous pouvez notifier les serveurs internes sans ouvrir votre pare-feu aux demandes entrantes provenant d'AppScan 360°.

Création et gestion des webhooks à l'aide de l'API REST

Pour créer, gérer et configurer des webhooks, utilisez l'API REST AppScan 360°. Les nœuds finaux des webhooks sont documentés dans la référence d'API publique :

API REST AppScan : nœuds finaux des webhooks

Pour créer un webhook, envoyez une requête POST au nœud final /api/v4/Webhooks avec les informations suivantes :

  • PresenceId : ID de l'instance Presence d'AppScan qui traite la requête de webhook
  • Uri : Nœud final HTTP à appeler lorsque l'événement est déclenché. L'URI peut inclure l'espace réservé{SubjectId}.
  • Event : Type d'événement qui déclenche le webhook (ScanExecutionCompleted ou ApplicationCountersChanged)
  • Globale : Valeur booléenne indiquant s'il s'agit d'un webhook global (applicable à toutes les applications ou à tous les groupes d'actifs) ou d'un webhook à portée (applicable uniquement à des applications ou groupes d'actifs spécifiques)
  • AssetGroupId : (facultatif) ID du groupe d'actifs auquel s'applique le webhook

Exemple : Webhook global pour la fin de l'exécution d'un examen

Cet exemple crée un webhook global qui se déclenche lorsqu'une exécution d'examen est terminée. Le webhook est appelé pour tous les examens au sein de l'organisation :

{
    "PresenceId": "1234",
    "Uri": "http://mysite.com/ScanEnded/{SubjectId}",
    "Event": "ScanExecutionCompleted",
    "Global": true
    }

Lorsque ce webhook est déclenché, AppScan 360° envoie une requête GET à votre service. La valeur {SubjectId} est remplacée par l'ID d'exécution d'examen :

GET /ScanEnded/9ea1fcb6-dc1d-443a-bfff-7465ced2ef1b HTTP/1.1 
    Host: mysite.com

Important : Le webhook n'envoie pas de données d'événement dans le corps de la requête. Pour récupérer des données supplémentaires (par exemple, la liste des problèmes trouvés au cours de l'examen), vous devez implémenter un service distinct qui gérera l'événement de webhook, se connectera à AppScan 360° en utilisant une clé d'API, puis récupérera les données requises auprès de l'API d'AppScan 360°.

Espace réservé d'URI de webhook

Lorsque vous définissez un URI de webhook, vous pouvez inclure l'espace réservé {SubjectId}. Cet espace réservé est remplacé par l'ID de l'objet de l'événement (généralement l'ID d'exécution de l'examen). Vous pouvez utiliser cette valeur pour transmettre le contexte d'événement de base à votre gestionnaire de webhooks.

Exemple d'URI avec espace réservé :

URI du webhook : http://myservice.com/ScanEnded/{SubjectId}

Si une exécution d'examen avec l'ID 9ea1fcb6-dc1d-443a-bfff-7465ced2ef1b se termine, le webhook est appelé à l'adresse suivante :

http://mysite.com/ScanEnded/9ea1fcb6-dc1d-443a-bfff-7465ced2ef1b

Contrôle d'accès au webhook

Pour créer ou modifier un webhook, vous devez disposer du droit pour Créer/modifier des webhooks dans AppScan 360°. Par défaut, cette autorisation est attribuée aux rôles Administrateur et Gestionnaire, et elle peut également être ajoutée aux rôles Personnalisé.

Vous pouvez définir un webhook au niveau de l'organisation ou pour un groupe d'actifs spécifique :

  • Un webhook au niveau de l'organisation est défini et géré par un Administrateur ou par un utilisateur doté d'un accès complet à tous les groupes.
  • Un webhook au niveau du groupe d'actifs peut être défini et géré par tout utilisateur doté d'un accès au groupe d'actifs et disposant du droit pour Créer/modifier des webhooks.

Portée d'un webhook

Vous pouvez définir un webhook comme étant global ou à portée.

Un webhook Global est déclenché à chaque fois qu'un événement qui correspond au type d'événement du webhook se produit au sein de l'organisation ou du groupe d'actifs (selon l'emplacement où le webhook est défini).

Un webhook qui n'est pas global peut être associé à une ou plusieurs portées. Une portée peut être une application spécifique ou, si le webhook est défini au niveau de l'organisation, un groupe d'actifs spécifique.

Un webhook à portée est déclenché uniquement si un événement se produit au sein de l'une des portées associées.

Exemple : Si le webhook est déclenché au moment de la fin de l'exécution de l'examen et que sa portée est une application spécifique, il est déclenché chaque fois qu'une exécution d'examen dans cette application se termine.

Création d'associations de webhooks pour des webhooks à portée

Si un webhook n'est pas global (c'est-à-dire si vous définissez "Global": false ), vous devez créer des associations pour spécifier les applications ou les groupes d'actifs auxquels le webhook s'applique. Créez ces associations à l'aide du nœud final de l'API des associations de webhooks.

Pour associer un webhook à des applications ou à des groupes d'actifs spécifiques, envoyez une requête POST au nœud final /api/v4/Webhooks/Associations/{id}, où {id} est l'ID du webhook renvoyé lorsque vous avez créé le webhook.

Exemple : Webhook à portée pour un groupe d'actifs spécifique

Commencez par créer un webhook à portée (non global) :

{
    "PresenceId": "1234",
    "Uri": "http://mysite.com/ScanEnded/{SubjectId}",
    "Event": "ScanExecutionCompleted",
    "Global": false,
    "AssetGroupId": "5678"
    }

Ce webhook ne se déclenche pas tant que vous n'avez pas créé d'associations. Ensuite, associez le webhook à des applications spécifiques en utilisant le nœud final des associations. Cela garantit que le webhook est déclenché uniquement pour les examens des applications associées au sein de ce groupe d'actifs.

Pour plus d'informations sur la création et la gestion des associations de webhooks, voir la documentation de l'API REST AppScan.