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 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.

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

Tous les champs 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 du webhook prennent en charge les macros utilisateur, toutes les macros prises en charge dans les notifications de problème 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, faute de quoi il ne sera pas valide. Il peut renvoyer un état OK accompagné d'une liste facultative d'étiquettes et de valeurs d'étiquettes (voir l'option Traiter les étiquettes) ou une chaîne d'erreur.

Notez que le script n'est exécuté qu'après la création d'une alerte. Si le script est configuré pour renvoyer et traiter des étiquettes, ces étiquettes ne seront pas résolues dans les macros {EVENT.TAGS} et {EVENT.RECOVERY.TAGS} du message de problème initial et des messages de rétablissement, car le script n'a pas encore eu le temps de s'exécuter.
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 de 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 étiquettes Cochez la case pour traiter les valeurs des propriétés JSON renvoyées comme des étiquettes. Ces étiquettes sont ajoutées aux étiquettes de problème existantes.
Notez que lors de l'utilisation des étiquettes de webhook, le webhook doit renvoyer un objet JSON contenant au moins un objet d'étiquettes vide : var result = {tags: {}};
Exemples d'étiquettes pouvant être renvoyées : jira-id:prod-1234, responsable:Jean Dupont, 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 étiquettes correspondantes).
Si cette option est activé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 activé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 activé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 message 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. Repérez 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 Utilisateurs > Utilisateurs et assignez le média webhook à un utilisateur existant ou créez un nouvel utilisateur pour représenter le webhook. Les étapes de configuration d'un support 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 Inclure une entrée dans le menu de l'événement). 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 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 des médias, 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 Médias et ajoutez un webhook avec les informations de contact requises. Si le webhook n'utilise pas de champ Envoyer à, saisissez n'importe quelle combinaison de caractères pris en charge pour 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 d'une action d'alerte, ajoutez cet utilisateur dans le champ Envoyer aux utilisateurs dans les 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.