4 Webhook

Vue d'ensemble

Le type de média webhook est utile pour effectuer des appels HTTP à l'aide d'un code JavaScript personnalisé afin de permettre une intégration simple avec des logiciels externes tels que des systèmes de helpdesk, des chats ou des messageries. Vous pouvez choisir d'importer une intégration fournie par Zabbix ou de créer une intégration personnalisée à partir de zéro.

Intégrations

Les intégrations suivantes sont disponibles et permettent d'utiliser des types de média webhook prédéfinis pour envoyer des notifications Zabbix vers :

En plus des services répertoriés ici, Zabbix peut être intégré à Spiceworks (aucun webhook n'est requis). Pour convertir les notifications Zabbix en tickets Spiceworks, créez un type de média e-mail et saisissez l'adresse e-mail du helpdesk Spiceworks (par exemple, help\@zabbix.on.spiceworks.com) dans les paramètres de profil d'un utilisateur Zabbix désigné.

Configuration

Pour commencer à utiliser une intégration webhook :

  1. Localisez le fichier .yaml requis dans le répertoire templates/media de la version téléchargée de Zabbix ou téléchargez-le depuis le dépôt git de Zabbix.
  2. Importez le fichier dans votre installation Zabbix. Le webhook apparaîtra dans la liste des types de média.
  3. Configurez le webhook conformément aux instructions du fichier Readme.md (vous pouvez cliquer sur le nom d’un webhook ci-dessus pour accéder rapidement au fichier Readme.md).

Pour créer un webhook personnalisé à partir de zéro :

  1. Accédez à Alertes > Types de média.
  2. Cliquez sur Créer un type de média.

L’onglet Type de média contient divers attributs spécifiques à ce type de média :

Tous les champs de saisie obligatoires sont marqués d’un astérisque rouge.

Les paramètres suivants sont spécifiques au type de média webhook :

Parameter Description
Parameters Spécifiez les variables du webhook sous forme de paires attribut-valeur.
Pour les webhooks préconfigurés, la liste des paramètres varie selon le service. Consultez le fichier Readme.md du webhook pour obtenir la description des paramètres.
Pour les nouveaux webhooks, plusieurs variables communes sont incluses par défaut (URL:<empty>, HTTPProxy:<empty>, To:{ALERT.SENDTO}, Subject:{ALERT.SUBJECT}, Message:{ALERT.MESSAGE}) ; vous pouvez les conserver ou les supprimer.

Les paramètres du webhook prennent en charge les macros utilisateur, toutes les macros prises en charge dans les notifications de problème et, en plus, les macros {ALERT.SENDTO}, {ALERT.SUBJECT} et {ALERT.MESSAGE}.

Si vous spécifiez un proxy HTTP, le champ prend en charge la même fonctionnalité que le champ HTTP proxy dans la configuration des éléments. La chaîne du proxy peut être préfixée par [scheme]:// pour spécifier le type de proxy utilisé (par exemple, https, socks4, socks5 ; voir la documentation).
Script Saisissez le code JavaScript dans l’éditeur modal qui s’ouvre lorsque vous cliquez dans le champ du paramètre ou sur l’icône en forme de crayon à côté. Ce code exécutera l’opération du webhook.
Le script est un code de fonction qui accepte des paires paramètre-valeur. Les valeurs doivent être converties en objets JSON à l’aide de la méthode JSON.parse(), par exemple : var params = JSON.parse(value);.

Le code a accès à tous les paramètres ; il peut effectuer des requêtes HTTP GET, POST, PUT et DELETE et contrôler les en-têtes HTTP ainsi que le corps de la requête.
Le script doit contenir un opérateur return, sinon il ne sera pas valide. Il peut renvoyer un statut OK avec une liste facultative de tags et de valeurs de tags (voir l’option Process tags) ou une chaîne d’erreur.

Les événements de rétablissement (qu’ils soient générés automatiquement ou à la suite d’une fermeture manuelle) sont créés par le serveur et incluent les tags d’événement résolus (y compris les tags hérités des modèles, des hôtes et des déclencheurs). Les scripts webhook sont exécutés après la création de l’alerte ; par conséquent, les tags renvoyés par un script webhook ne sont ajoutés qu’après la création initiale de l’alerte et ne seront pas présents dans les macros {EVENT.TAGS} et {EVENT.RECOVERY.TAGS} du message initial de problème ou du message de rétablissement immédiat.
Remarque : il est recommandé d’utiliser des variables locales (par ex. var local = 1) plutôt qu’une variable globale (par ex. global = 1) afin de garantir que chaque script fonctionne sur ses propres données et d’éviter les collisions entre appels simultanés (voir les problèmes connus).

Voir aussi : Directives de développement des webhooks, Exemples de scripts webhook, Objets JavaScript supplémentaires.
Timeout Délai d’expiration de l’exécution JavaScript (1-60s, 30s par défaut).
Les suffixes de temps sont pris en charge, par ex., 30s, 1m.
Process tags Cochez la case pour traiter les valeurs des propriétés JSON renvoyées comme des tags. Ces tags sont ajoutés à tous les tags de problème existants.
Notez que lors de l’utilisation de tags webhook, le webhook doit renvoyer un objet JSON contenant au minimum un objet tags vide : var result = {tags: {}};
Exemples de tags pouvant être renvoyés : jira-id:prod-1234, responsible:John Smith, processed:<no value>
Include event menu entry Cochez la case pour inclure une entrée dans le menu d’événement pointant vers un ticket externe créé.
Une entrée sera incluse pour chaque webhook activé ayant cette case cochée. Notez que si les paramètres Menu entry name et Menu entry URL contiennent des macros {EVENT.TAGS.<tag name>}, une entrée ne sera incluse que si ces macros peuvent être résolues (c’est-à-dire si l’événement a ces tags définis).
Si cette option est cochée, le webhook ne doit pas être utilisé pour envoyer des notifications à différents utilisateurs (envisagez plutôt de créer un utilisateur dédié) et ne doit pas être utilisé dans plusieurs actions d’alerte pour un seul événement de problème.
Menu entry name Spécifiez le nom de l’entrée de menu.
La macro {EVENT.TAGS.<tag name>} est prise en charge.
Ce champ n’est obligatoire que si Include event menu entry est coché.
Menu entry URL Spécifiez l’URL sous-jacente de l’entrée de menu.
La macro {EVENT.TAGS.<tag name>} est prise en charge.
Ce champ n’est obligatoire que si Include event menu entry est coché.

Consultez les paramètres communs des types de média pour plus de détails sur la configuration des messages par défaut et des options de traitement des alertes.

Même si un webhook n’utilise pas les messages par défaut, des modèles de message pour les types d’opération utilisés par ce webhook doivent tout de même être définis.

Test

Pour tester un type de média webhook configuré :

  1. Localisez le webhook concerné dans la liste des types de média.
  2. Cliquez sur Test dans la dernière colonne de la liste (une fenêtre de test s'ouvrira).
  3. Modifiez les valeurs des paramètres du webhook selon les besoins. Remplacez les macros par des valeurs d'exemple ; sinon, les macros ne seront pas résolues et le test échouera.
  4. Cliquez sur Test.

Le remplacement ou la suppression de valeurs dans la fenêtre de test n'affecte que la procédure de test ; les valeurs réelles des attributs du webhook resteront inchangées.

Pour afficher les entrées du journal de test du type de média sans quitter la fenêtre de test, cliquez sur Open log (une nouvelle fenêtre contextuelle s'ouvrira).

Si le test du webhook réussit :

  • Le message « Media type test successful. » s’affiche.
  • La réponse du serveur apparaît dans le champ gris Response.
  • Le type de réponse (JSON ou String) est indiqué sous le champ Response.

Si le test du webhook échoue :

  • Le message « Media type test failed. » s’affiche, suivi de détails supplémentaires sur l’échec.

Support utilisateur

Une fois le type de média configuré, accédez à la section Users > Users et assignez le média webhook à un utilisateur existant ou créez un nouvel utilisateur pour représenter le webhook. Les étapes de configuration du média utilisateur pour un utilisateur existant, communes à tous les types de médias, sont décrites sur la page Types de médias.

Si un webhook utilise des tags pour stocker l'ID du ticket\message, évitez d'assigner le même webhook comme média à différents utilisateurs, car cela peut provoquer des erreurs de webhook (cela s'applique à la majorité des webhooks qui utilisent l'option Include event menu entry). Dans ce cas, la bonne pratique consiste à créer un utilisateur dédié pour représenter le webhook :

  1. Après avoir configuré le type de média webhook, accédez à la section Users > Users et créez un utilisateur Zabbix dédié pour représenter le webhook - par exemple, avec le nom d'utilisateur Slack pour le webhook Slack. Tous les paramètres, à l'exception du média, peuvent être laissés à leurs valeurs par défaut, car cet utilisateur ne se connectera pas à Zabbix.
  2. Dans le profil utilisateur, accédez à l'onglet Media et ajoutez un webhook avec les informations de contact requises. Si le webhook n'utilise pas de champ Send to, saisissez n'importe quelle combinaison de caractères pris en charge afin de contourner les exigences de validation.
  3. Accordez à cet utilisateur au moins les autorisations de lecture sur tous les hôtes pour lesquels il doit envoyer des alertes.

Lors de la configuration de l'action d'alerte, ajoutez cet utilisateur dans le champ Send to users des détails de l'opération - cela indiquera à Zabbix d'utiliser le webhook pour les notifications de cette action.

Configuration des actions d'alerte

Les actions déterminent quelles notifications doivent être envoyées via le webhook. Les étapes de configuration des actions impliquant des webhooks sont les mêmes que pour tous les autres types de média, à l'exception des points suivants :

  • Si un webhook utilise des balises de webhook pour stocker l'ID du ticket\message et gérer les opérations de mise à jour\résolution, évitez d'utiliser le même webhook dans plusieurs actions d'alerte pour un même événement de problème. Si {EVENT.TAGS.<tag name>} existe et est mis à jour dans le webhook, sa valeur résultante sera indéfinie. Pour éviter cela, utilisez un nouveau nom de balise dans le webhook pour stocker les valeurs mises à jour. Cela s'applique aux webhooks Jira, Jira Service Desk, Mattermost, Opsgenie, OTRS, Redmine, ServiceNow, Slack, Zammad et Zendesk fournis par Zabbix, ainsi qu'à la plupart des webhooks utilisant l'option Include event menu entry. Notez toutefois qu'un même webhook peut être utilisé dans plusieurs opérations ou étapes d'escalade de la même action, ainsi que dans différentes actions qui ne seront pas déclenchées par le même événement de problème en raison de conditions différentes.
  • Lors de l'utilisation d'un webhook dans des actions pour des événements internes, veillez à cocher la case Custom message et à définir un message personnalisé dans la configuration de l'opération de l'action. Sinon, aucune notification ne sera envoyée.