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 les 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 email et saisissez l'adresse e-mail du helpdesk Spiceworks (par exemple, [email protected]) 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 de Zabbix téléchargée 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.
  3. Saisissez les paramètres du type de média webhook dans le formulaire.

L'onglet Type de média contient différents attributs spécifiques à ce type de média :

Tous les champs de saisie obligatoires sont signalés par un astérisque rouge.

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

Paramètre Description
Paramètres 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 courantes 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 des webhooks prennent en charge les macros utilisateur, toutes les macros prises en charge dans les notifications de problèmes et, en outre, les macros {ALERT.SENDTO}, {ALERT.SUBJECT} et {ALERT.MESSAGE}.

Si vous spécifiez un proxy HTTP, le champ prend en charge les mêmes fonctionnalités que le champ Proxy HTTP de la configuration de l'élément. La chaîne du proxy peut être précédée de [scheme]:// afin de spécifier le type de proxy utilisé (par exemple, https, socks4, socks5 ; consultez 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 située à côté. Ce code exécutera l'opération du webhook.
Le script est une 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, prendre en charge des méthodes supplémentaires telles que CONNECT, PATCH, HEAD, OPTIONS et TRACE, 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 état OK accompagné d'une liste facultative de tags et de valeurs de tags (voir l'option Traiter les 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 de l'événement résolu (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 sont ajoutés uniquement 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 du problème ou du message de rétablissement immédiat.
Remarque : Il est recommandé d'utiliser des variables locales (par exemple, var local = 1) plutôt qu'une variable globale (par exemple, global = 1) afin de garantir que chaque script fonctionne avec ses propres données et d'éviter les collisions entre appels simultanés (voir les problèmes connus).

Voir également : Directives de développement des webhooks, Exemples de scripts webhook, Objets JavaScript supplémentaires.
Délai d'expiration Délai d'expiration de l'exécution JavaScript (1 à 60 s, 30 s par défaut).
Les suffixes de temps sont pris en charge (par exemple, 30s, 1m).
Traiter les tags Cochez la case pour traiter les valeurs des propriétés JSON renvoyées comme des tags. Ces tags sont ajoutés aux tags existants du problème.
Notez que lors de l'utilisation des tags webhook, le webhook doit renvoyer un objet JSON contenant au moins un objet de tags vide : var result = {tags: {}};
Exemples de tags pouvant être renvoyés : jira-id:prod-1234, responsible:John Smith, processed:<no value>
Inclure une entrée dans le menu des événements Cochez la case pour inclure dans le menu des événements une entrée contenant un lien vers un ticket externe créé.
Une entrée sera incluse pour chaque webhook activé dont cette case est cochée. Notez que si les paramètres Nom de l'entrée de menu et URL de l'entrée de menu 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 possède les tags correspondants).
Si cette option est sélectionné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.
Nom de l'entrée de menu Spécifiez le nom de l'entrée de menu.
La macro {EVENT.TAGS.<tag name>} est prise en charge.
Ce champ est obligatoire uniquement si l'option Inclure une entrée dans le menu des événements est sélectionnée.
URL de l'entrée de menu Spécifiez l'URL sous-jacente de l'entrée de menu.
La macro {EVENT.TAGS.<tag name>} est prise en charge.
Ce champ est obligatoire uniquement si l'option Inclure une entrée dans le menu des événements est sélectionnée.

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

Même si un webhook n'utilise pas de messages par défaut, les modèles de messages correspondant aux 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 Tester dans la dernière colonne de la liste (une fenêtre de test s’ouvrira).
  3. Modifiez les valeurs des paramètres du webhook si nécessaire.
    Remplacez les macros par des valeurs d’exemple ; sinon, les macros ne seront pas résolues et le test échouera.
  4. Cliquez sur Tester.

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

Pour consulter les entrées du journal de test du type de média sans quitter la fenêtre de test, cliquez sur Ouvrir le journal (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.

Média utilisateur

Une fois le type de média configuré, accédez à la section Utilisateurs > Utilisateurs et affectez le média webhook à un utilisateur existant, ou créez un nouvel utilisateur pour représenter le webhook. Les étapes de configuration des médias 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 étiquettes pour stocker l’ID du ticket\message, évitez d’affecter le même webhook comme média à différents utilisateurs, car cela peut entraîner des erreurs du webhook (cela concerne la majorité des webhooks qui utilisent l’option Inclure l’entrée de menu de l’événement). Dans ce cas, il est recommandé de 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 Utilisateurs > Utilisateurs 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 conserver leurs valeurs par défaut, car cet utilisateur ne se connectera pas à Zabbix.
  2. Dans le profil utilisateur, accédez à l’onglet Média et ajoutez un webhook avec les coordonnées requises. Si le webhook n’utilise pas de champ Envoyer à, saisissez une combinaison quelconque de caractères pris en charge afin de satisfaire aux exigences de validation.
  3. Accordez à cet utilisateur au moins les permissions de lecture sur tous les hôtes pour lesquels il doit envoyer les alertes.

Lors de la configuration d’une action d’alerte, ajoutez cet utilisateur dans le champ Envoyer aux utilisateurs des détails de l’opération. Zabbix utilisera ainsi 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 cas 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 seul é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 seul 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.