4 webhook

Übersicht

Der webhook-Medientyp ist nützlich, um HTTP-Aufrufe mithilfe von benutzerdefiniertem JavaScript-Code für eine unkomplizierte Integration mit externer Software wie Helpdesk-Systemen, Chats oder Messengern durchzuführen. Sie können eine von Zabbix bereitgestellte Integration importieren oder eine benutzerdefinierte Integration von Grund auf neu erstellen.

Integrationen

Die folgenden Integrationen sind verfügbar und ermöglichen die Verwendung vordefinierter webhook-Medientypen zum Weiterleiten von Zabbix-Benachrichtigungen an:

Zusätzlich zu den hier aufgeführten Diensten kann Zabbix mit Spiceworks integriert werden (dabei ist kein webhook erforderlich). Um Zabbix-Benachrichtigungen in Spiceworks-Tickets umzuwandeln, erstellen Sie einen E-Mail-Medientyp und tragen Sie die Helpdesk-E-Mail-Adresse von Spiceworks (z. B. [email protected]) in den Profileinstellungen eines dafür vorgesehenen Zabbix-Benutzers ein.

Konfiguration

So beginnen Sie mit der Verwendung einer webhook-Integration:

  1. Suchen Sie die erforderliche .yaml-Datei im Verzeichnis templates/media der heruntergeladenen Zabbix-Version oder laden Sie sie aus dem git-Repository von Zabbix herunter.
  2. Importieren Sie die Datei in Ihre Zabbix-Installation. Der webhook wird in der Liste der Medientypen angezeigt.
  3. Konfigurieren Sie den webhook gemäß den Anweisungen in der Datei Readme.md (Sie können oben auf den Namen eines webhooks klicken, um schnell auf Readme.md zuzugreifen).

So erstellen Sie einen benutzerdefinierten webhook von Grund auf:

  1. Gehen Sie zu Alarme > Medientypen.
  2. Klicken Sie auf Medientyp erstellen.

Die Registerkarte Medientyp enthält verschiedene Attribute, die für diesen Medientyp spezifisch sind:

Alle Pflichtfelder sind mit einem roten Sternchen gekennzeichnet.

Die folgenden Parameter sind für den webhook-Medientyp spezifisch:

Parameter Beschreibung
Parameter Geben Sie die webhook-Variablen als Attribut-Wert-Paare an.
Bei vorkonfigurierten webhooks variiert die Liste der Parameter je nach Dienst. Eine Beschreibung der Parameter finden Sie in der Datei Readme.md des webhooks.
Bei neuen webhooks sind standardmäßig mehrere allgemeine Variablen enthalten (URL:<empty>, HTTPProxy:<empty>, To:{ALERT.SENDTO}, Subject:{ALERT.SUBJECT}, Message:{ALERT.MESSAGE}); Sie können diese beibehalten oder entfernen.

Webhook-Parameter unterstützen Benutzermakros, alle Makros, die in Problembenachrichtigungen unterstützt werden, sowie zusätzlich die Makros {ALERT.SENDTO}, {ALERT.SUBJECT} und {ALERT.MESSAGE}.

Wenn Sie einen HTTP-Proxy angeben, unterstützt das Feld dieselbe Funktionalität wie das Feld HTTP-Proxy in der Datenpunkt-Konfiguration. Der Proxy-String kann mit [scheme]:// vorangestellt werden, um anzugeben, welche Art von Proxy verwendet wird (z. B. https, socks4, socks5; siehe Dokumentation).
Skript Geben Sie JavaScript-Code im modalen Editor ein, der geöffnet wird, wenn Sie in das Parameterfeld oder auf das Stiftsymbol daneben klicken. Dieser Code führt die webhook-Operation aus.
Das Skript ist eine Funktionsdefinition, die Parameter-Wert-Paare akzeptiert. Die Werte sollten mithilfe der Methode JSON.parse() in JSON-Objekte konvertiert werden, zum Beispiel: var params = JSON.parse(value);.

Der Code hat Zugriff auf alle Parameter, kann HTTP-GET-, POST-, PUT- und DELETE-Anfragen ausführen, zusätzliche Methoden wie CONNECT, PATCH, HEAD, OPTIONS und TRACE unterstützen und HTTP-Header sowie den Anfragetext steuern.
Das Skript muss einen return-Operator enthalten, andernfalls ist es nicht gültig. Es kann den Status OK zusammen mit einer optionalen Liste von Tags und Tag-Werten (siehe Option Tags verarbeiten) oder eine Fehlerzeichenfolge zurückgeben.

Beachten Sie, dass das Skript erst ausgeführt wird, nachdem ein Alarm erstellt wurde. Wenn das Skript so konfiguriert ist, dass es Tags zurückgibt und verarbeitet, werden diese Tags in den Makros {EVENT.TAGS} und {EVENT.RECOVERY.TAGS} der ursprünglichen Problemmeldung und der Wiederherstellungsmeldungen nicht aufgelöst, da das Skript noch nicht genügend Zeit zur Ausführung hatte.
Hinweis: Es wird empfohlen, lokale Variablen (z. B. var local = 1) anstelle globaler Variablen (z. B. global = 1) zu verwenden, damit jedes Skript mit seinen eigenen Daten arbeitet und Kollisionen zwischen gleichzeitigen Aufrufen vermieden werden (siehe bekannte Probleme).

Siehe auch: Richtlinien für die webhook-Entwicklung, Beispiele für webhook-Skripte, Zusätzliche JavaScript-Objekte.
Zeitüberschreitung Zeitüberschreitung bei der JavaScript-Ausführung (1-60 s, Standardwert 30 s).
Zeitsuffixe werden unterstützt (z. B. 30s, 1m).
Tags verarbeiten Aktivieren Sie das Kontrollkästchen, um zurückgegebene JSON-Eigenschaftswerte als Tags zu verarbeiten. Diese Tags werden zu allen vorhandenen Problem-Tags hinzugefügt.
Beachten Sie, dass der webhook bei Verwendung von webhook-Tags ein JSON-Objekt zurückgeben muss, das mindestens ein leeres Tags-Objekt enthält: var result = {tags: {}};
Beispiele für Tags, die zurückgegeben werden können: jira-id:prod-1234, responsible:John Smith, processed:<no value>
Ereignismenüeintrag einschließen Aktivieren Sie das Kontrollkästchen, um einen Eintrag im Ereignismenü einzuschließen, der auf ein erstelltes externes Ticket verweist.
Für jeden aktivierten webhook, bei dem dieses Kontrollkästchen aktiviert ist, wird ein Eintrag eingeschlossen. Beachten Sie, dass ein Eintrag nur dann eingeschlossen wird, wenn die Makros {EVENT.TAGS.<tag name>} in den Parametern Name des Menüeintrags und URL des Menüeintrags aufgelöst werden können (das heißt, wenn für das Ereignis diese Tags definiert sind).
Wenn diese Option aktiviert ist, sollte der webhook nicht zum Senden von Benachrichtigungen an verschiedene Benutzer verwendet werden (erwägen Sie stattdessen, einen dedizierten Benutzer zu erstellen) und nicht in mehreren Alarmaktionen für ein einzelnes Problemereignis verwendet werden.
Name des Menüeintrags Geben Sie den Namen des Menüeintrags an.
Das Makro {EVENT.TAGS.<tag name>} wird unterstützt.
Dieses Feld ist nur dann ein Pflichtfeld, wenn Ereignismenüeintrag einschließen aktiviert ist.
URL des Menüeintrags Geben Sie die zugrunde liegende URL des Menüeintrags an.
Das Makro {EVENT.TAGS.<tag name>} wird unterstützt.
Dieses Feld ist nur dann ein Pflichtfeld, wenn Ereignismenüeintrag einschließen aktiviert ist.

Details zur Konfiguration von Standardnachrichten und Optionen zur Alarmverarbeitung finden Sie unter allgemeine Medientyp-Parameter.

Auch wenn ein webhook keine Standardnachrichten verwendet, müssen Nachrichtenvorlagen für die von diesem webhook verwendeten Operationstypen weiterhin definiert werden.

Testen

So testen Sie einen konfigurierten webhook-Medientyp:

  1. Suchen Sie den relevanten webhook in der Liste der Medientypen.
  2. Klicken Sie in der letzten Spalte der Liste auf Test (ein Testfenster wird geöffnet).
  3. Bearbeiten Sie die Werte der webhook-Parameter nach Bedarf. Ersetzen Sie Makros durch Beispielwerte; andernfalls werden Makros nicht aufgelöst, und der Test schlägt fehl.
  4. Klicken Sie auf Test.

Das Ersetzen oder Löschen von Werten im Testfenster wirkt sich nur auf den Testvorgang aus, die tatsächlichen Attributwerte des webhooks bleiben unverändert.

Um Testprotokolleinträge des Medientyps anzuzeigen, ohne das Testfenster zu verlassen, klicken Sie auf Open log (ein neues Popup-Fenster wird geöffnet).

Wenn der webhook-Test erfolgreich ist:

  • Die Meldung „Medientyp-Test erfolgreich.“ wird angezeigt.
  • Die Server-Antwort erscheint im grauen Feld Antwort.
  • Der Antworttyp (JSON oder String) wird unterhalb des Feldes Antwort angegeben.

Wenn der webhook-Test fehlschlägt:

  • Die Meldung „Medientyp-Test fehlgeschlagen.“ wird angezeigt, gefolgt von zusätzlichen Details zum Fehler.

Benutzermedien

Sobald der Medientyp konfiguriert ist, gehen Sie zum Abschnitt Benutzer > Benutzer und weisen Sie das webhook-Medium einem vorhandenen Benutzer zu oder erstellen Sie einen neuen Benutzer, der das webhook repräsentiert. Die Schritte zum Einrichten von Benutzermedien für einen vorhandenen Benutzer, die für alle Medientypen gleich sind, werden auf der Seite Medientypen beschrieben.

Wenn ein webhook Tags zum Speichern der Ticket\Nachrichten-ID verwendet, vermeiden Sie es, dasselbe webhook als Medium verschiedenen Benutzern zuzuweisen, da dies zu webhook-Fehlern führen kann (gilt für die Mehrheit der webhooks, die die Option Ereignismenüeintrag einschließen verwenden). In diesem Fall empfiehlt es sich, einen dedizierten Benutzer zu erstellen, der das webhook repräsentiert:

  1. Gehen Sie nach der Konfiguration des webhook-Medientyps zum Abschnitt Benutzer > Benutzer und erstellen Sie einen dedizierten Zabbix-Benutzer, der das webhook repräsentiert – zum Beispiel mit dem Benutzernamen Slack für das Slack-webhook. Alle Einstellungen außer den Medien können auf ihren Standardwerten belassen werden, da sich dieser Benutzer nicht bei Zabbix anmelden wird.
  2. Wechseln Sie im Benutzerprofil zur Registerkarte Medien und fügen Sie ein webhook hinzu mit den erforderlichen Kontaktinformationen. Wenn das webhook kein Feld Senden an verwendet, geben Sie eine beliebige Kombination unterstützter Zeichen ein, um die Validierungsanforderungen zu umgehen.
  3. Gewähren Sie diesem Benutzer mindestens Lese-Berechtigungen für alle Hosts, für die er die Warnmeldungen senden soll.

Fügen Sie bei der Konfiguration der Aktionsbenachrichtigung diesen Benutzer im Feld An Benutzer senden in den Betriebsdetails hinzu – dadurch weist Zabbix an, das webhook für Benachrichtigungen aus dieser Aktion zu verwenden.

Konfigurieren von Alarmierungsaktionen

Aktionen bestimmen, welche Benachrichtigungen über den webhook gesendet werden sollen. Die Schritte zum Konfigurieren von Aktionen, die webhooks betreffen, sind dieselben wie bei allen anderen Medientypen, mit folgenden Ausnahmen:

  • Wenn ein webhook webhook-Tags verwendet, um Ticket\Nachrichten-ID zu speichern und Aktualisierungs\Lösungs-Operationen zu verarbeiten, vermeiden Sie die Verwendung desselben webhook in mehreren Alarmierungsaktionen für ein einzelnes Problemereignis. Wenn {EVENT.TAGS.<tag name>} existiert und im webhook aktualisiert wird, ist sein resultierender Wert undefiniert. Um dies zu vermeiden, verwenden Sie im webhook einen neuen Tag-Namen zum Speichern aktualisierter Werte. Dies gilt für die von Zabbix bereitgestellten webhooks Jira, Jira Service Desk, Mattermost, Opsgenie, OTRS, Redmine, ServiceNow, Slack, Zammad und Zendesk sowie für die meisten webhooks, die die Option Include event menu entry verwenden. Beachten Sie jedoch, dass ein einzelner webhook in mehreren Operationen oder Eskalationsschritten derselben Aktion sowie in verschiedenen Aktionen verwendet werden kann, die aufgrund unterschiedlicher Bedingungen nicht durch dasselbe Problemereignis ausgelöst werden.
  • Wenn Sie einen webhook in Aktionen für interne Ereignisse verwenden, stellen Sie sicher, dass Sie das Kontrollkästchen Custom message aktivieren und in der Konfiguration der Aktionsoperation eine benutzerdefinierte Nachricht festlegen. Andernfalls wird keine Benachrichtigung gesendet.