Webhook

Description

Un webhook est un mécanisme qui permet à GLPI d'envoyer automatiquement des notifications à un système externe (tel qu'un autre logiciel, une API ou un service web) lorsqu'un événement se produit dans GLPI.

Exemples : recevoir une alerte (dans un système de messagerie d'entreprise comme Mattermost) lorsqu'un ticket critique est créé, ou synchroniser l'inventaire avec un système de facturation (s'il fournit une API pour recevoir le webhook).

Comment ça marche ?

Configurez un webhook dans GLPI en spécifiant l'événement déclencheur, l'objet associé, l'URL de destination et les données à envoyer.

Lorsque l'événement se produit, GLPI récupère les informations, prépare les données et place le webhook dans une file d'attente. Tout comme les Notifications régulières de GLPI, une action automatique envoie ensuite la requête HTTP à l'URL du webhook. Le système de destination reçoit alors les données et peut les traiter.

Accéder à la configuration

1. Allez dans Administration > Configuration > Webhooks

2. Cliquez sur + Ajouter

Formulaire de configuration de base

• Nom, Commentaires, Actif, Catégorie : le webhook se voit attribuer un nom, un commentaire optionnel, une catégorie, et peut être activé ou désactivé.

• Entité : détermine la portée du webhook. L'entité dans laquelle le webhook est créé agit comme racine ; la sélection d'entités enfants étend le webhook aux événements se produisant dans toutes les sous-entités sous cette racine.

• Type d'objet : spécifie le type d'objet GLPI qui déclenche le webhook (par exemple, Ticket, Utilisateur, Ordinateur).

• Événement : définit l'action sur le type d'objet sélectionné qui déclenchera le webhook (par exemple, création, mise à jour, suppression).

• Nombre de tentatives : définit le nombre de fois que GLPI tentera de renvoyer le webhook si la requête HTTP initiale échoue.

Configuration de la cible

• URL : l'adresse de destination du webhook. HTTPS est fortement recommandé. Des balises de remplacement (placeholder tags) du payload ou des valeurs d'en-tête peuvent être utilisées.

• Méthode HTTP : la méthode utilisée pour envoyer la requête du webhook ;

  • POST : les données du webhook sont envoyées dans le corps de la requête HTTP, généralement pour créer une nouvelle ressource ou déclencher une action sur le système de destination.

  • GET : les données du webhook sont envoyées dans l'URL sous forme de paramètres de requête, transmettant des informations de GLPI au système de destination.

  • UPDATE : les données du webhook sont envoyées dans le corps pour mettre à jour une ressource existante sur le système de destination.

  • PATCH : les données du webhook sont envoyées dans le corps pour mettre à jour partiellement une ressource existante, en modifiant uniquement les champs spécifiés.

  • PUT : les données du webhook sont envoyées dans le corps pour remplacer entièrement une ressource existante sur le système de destination.

• Enregistrer le corps de la réponse : stocke la réponse renvoyée par le système de destination après l'appel du webhook.

• Journaliser dans l'historique de l'élément : enregistre l'exécution du webhook et sa réponse dans l'historique de l'élément GLPI déclencheur.

Filtres

Par défaut, un webhook est déclenché pour tous les objets du itemtype sélectionné. Les filtres permettent de restreindre la portée, par exemple aux tickets critiques uniquement ou aux ordinateurs d'une marque spécifique.

Les filtres sont configurés à l'aide de l'interface standard du moteur de recherche de GLPI. Les critères peuvent être définis et enregistrés pour être réutilisés, et une fonction Aperçu permet d'afficher les résultats potentiels correspondant au filtre avant de l'appliquer au webhook.

Sécurité

Clé secrète

Le Secret est une clé partagée entre GLPI et le système cible (transmise dans un en-tête), utilisée pour signer les requêtes de webhook envoyées par GLPI.

Ce secret est crucial pour l'authentification, car il permet au serveur cible de vérifier que la requête provient bien de GLPI et non d'un imposteur.

Il assure également l'intégrité en permettant au serveur cible de recalculer et de comparer une signature (sha256) générée à partir du payload de la requête en utilisant le même secret ; si les signatures correspondent, la requête est confirmée comme authentique et inchangée.

De plus, le secret améliore la sécurité en empêchant les attaquants de forger des requêtes valides ou de falsifier les données pendant la transmission.

Délai d'expiration

Le Délai d'expiration définit une fenêtre temporelle spécifique (par exemple, 10 heures) pendant laquelle une requête de webhook reste valide.

Ce paramètre est essentiel pour prévenir les attaques par rejeu (replay attacks), car il garantit que même si un acteur malveillant intercepte une requête légitime, il ne pourra pas la réutiliser une fois le délai expiré.

De plus, il impose une validité temporaire, garantissant que seules les requêtes récentes et pertinentes sont traitées, minimisant ainsi le risque que des requêtes obsolètes ou frauduleuses soient acceptées par le système de destination.

Défi CRA

Le CRA (Challenge-Response Authentication) est un mécanisme de sécurité dans lequel le système cible émet un "défi" (challenge) — généralement une chaîne aléatoire ou un jeton — à GLPI, obligeant GLPI à générer et à renvoyer une réponse valide, souvent à l'aide d'un secret partagé ou d'une clé privée.

Ce processus est essentiel car il vérifie l'identité du serveur GLPI, garantissant que seul un serveur autorisé disposant des bonnes informations d'identification peut répondre avec succès au défi.

Le CRA est particulièrement précieux dans les environnements à haute sécurité, où la confirmation que le serveur cible communique exclusivement avec l'instance GLPI authentique est essentielle pour maintenir la confiance et prévenir les accès non autorisés.

Authentification OAuth

OAuth est une norme d'autorisation ouverte qui permet à GLPI d'obtenir de manière sécurisée un jeton d'accès auprès d'un serveur d'autorisation dédié, lequel est ensuite inclus dans les requêtes de webhook pour authentifier son identité.

Pour utiliser OAuth, GLPI nécessite trois éléments clés :

• l'URL du point de terminaison de jeton du serveur OAuth ;

• un ID client (un identifiant public enregistré auprès du serveur OAuth) ;

• et un Secret client (une clé confidentielle partagée uniquement entre GLPI et le serveur OAuth).

Résumé des options de sécurité des webhooks

Éditeur de payload

Le payload d'un webhook GLPI fait référence aux données structurées envoyées dans le cadre d'une requête (généralement au format JSON) au système cible.

Cette charge utile contient les détails essentiels relatifs à un événement spécifique, permettant au système récepteur de traiter ou de répondre à l'événement en conséquence.

Lorsqu'un webhook est créé dans GLPI, une charge utile par défaut est automatiquement affichée et utilisée.

Cette charge utile inclut des informations de base sur l'élément qui a déclenché le webhook, ainsi que des détails sur l'événement lui-même.

Pour personnaliser entièrement la charge utile — par exemple, en ajoutant des champs spécifiques, en restructurant les données ou en incluant un contexte supplémentaire — il est possible de désactiver l'option "Utiliser la charge utile par défaut" et de définir votre propre format de charge utile.

Actualiser la page après avoir vidé l'éditeur et enregistré restaure la charge utile à son état par défaut en mode édition.

Lors de la personnalisation de la charge utile du webhook, l'éditeur de charge utile inclut une fonction d'autocomplétion qui s'active dès que vous tapez {{.

Cette fonctionnalité vous aide à insérer rapidement des variables dynamiques liées à l'élément déclencheur, telles que {{item.id}}, {{item.name}}, ou {{item.status.name}}, etc.

Ces variables sont automatiquement remplacées par les valeurs réelles de l'élément qui a déclenché le webhook — comme un ticket, un actif ou un utilisateur — garantissant que la charge utile envoyée aux systèmes externes est toujours précise et contextuellement pertinente.

Exemple de charge utile de webhook pour Mattermost

Lors de la configuration d'un webhook dans GLPI pour envoyer des notifications à Mattermost, vous pouvez personnaliser la charge utile pour qu'elle corresponde au format attendu par Mattermost. Voici un exemple de ce à quoi pourrait ressembler la charge utile :

{
  "text": "🚨 Nouveau ticket critique !",
  "attachments": [
    {
      "color": "danger",
      "title": "Ticket #{{ item.id }}",
      "text": "{{ item.name }}",
      "fields": [
        {
          "title": "Catégorie",
          "value": "{{ item.category.name }}",
          "short": true
        },
        {
          "title": "Entité",
          "value": "{{ item.entity.completename }}",
          "short": true
        }
      ]
    }
  ]
}

Lorsque cette charge utile est envoyée à Mattermost, elle sera rendue sous forme de carte de message enrichie, similaire à ceci :

En-têtes personnalisés

Cette section de configuration permet aux utilisateurs de définir des en-têtes HTTP personnalisés qui seront inclus dans la requête webhook sortante envoyée au système cible.

Les en-têtes personnalisés peuvent servir plusieurs objectifs clés :

• Authentification et autorisation : Des en-têtes tels que Authorization, API-Key ou des jetons personnalisés peuvent être ajoutés pour authentifier la requête webhook auprès du système cible ;

• Spécification du type de contenu : Vous pouvez définir explicitement le format de la charge utile (par exemple, Content-Type: application/json, Content-Type: application/xml) pour garantir que le système cible interprète correctement les données ;

• Métadonnées et contexte : Les en-têtes personnalisés peuvent inclure des métadonnées supplémentaires, telles que des identifiants de requête, des horodatages ou des détails spécifiques à l'environnement, qui aident le système cible à traiter ou à acheminer la requête de manière appropriée ;

• Compatibilité avec les API : De nombreuses API tierces nécessitent des en-têtes spécifiques pour fonctionner correctement. Les en-têtes personnalisés permettent aux webhooks GLPI de répondre à ces exigences de manière transparente.

Journaux des requêtes

L'onglet Journaux des requêtes liste tous les webhooks liés à celui en cours : ceux déjà envoyés, ceux en attente d'envoi, etc. Il fonctionne de la même manière que la vue Webhooks en file d'attente, mais est spécifique au webhook sélectionné.

Chaque entrée affiche son code d'état, et vous pouvez utiliser le bouton Forcer l'envoi pour déclencher manuellement la livraison d'un webhook en attente. Vous pouvez également cliquer sur l'ID d'une entrée de journal de requête pour afficher ses informations détaillées.

Aperçu

L'onglet Aperçu vous permet (1) de sélectionner un élément disponible dans GLPI (seuls les éléments correspondant au type d'élément configuré du webhook sont listés). Il affiche à la fois les (2) données de l'API GLPI (la source de données interne utilisée par le webhook) et les (3) données de la charge utile qui seront envoyées au système externe.

Webhooks en file d'attente

Lorsqu'un événement se produit, GLPI n'envoie pas le webhook immédiatement. Au lieu de cela, il est placé dans une file d'attente (glpi_queuedwebhooks). Cette approche évite de ralentir l'interface utilisateur.

Une Action automatique (queuedwebhook) traite automatiquement la file d'attente :

• Récupère les webhooks en attente

• Envoie des requêtes HTTP

• Gère les erreurs et les nouvelles tentatives

• Met à jour les statuts des webhooks

Vous pouvez visualiser la file d'attente dans Administration > Configuration > Webhooks > File d'attente des webhooks :

• Voir les webhooks en attente

• Forcer manuellement l'envoi

• Vérifier les codes d'état de réponse

• Renvoyer les webhooks échoués

Une autre Action automatique (queuedwebhookclean) nettoie automatiquement la file d'attente :

• Supprime les anciens webhooks envoyés avec succès (après X jours)

• Supprime les webhooks qui ont atteint le nombre maximum de tentatives de renvoi