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, um Zabbix-Benachrichtigungen an folgende Dienste zu senden:

Zusätzlich zu den hier aufgeführten Diensten kann Zabbix auch in Spiceworks integriert werden (es ist kein webhook erforderlich). Um Zabbix-Benachrichtigungen in Spiceworks-Tickets umzuwandeln, erstellen Sie einen E-Mail-Medientyp und geben Sie die Spiceworks-Helpdesk-E-Mail-Adresse (z. B. help\@zabbix.on.spiceworks.com) 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 Zabbix-git repository 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 webhook klicken, um schnell auf Readme.md zuzugreifen).

So erstellen Sie einen benutzerdefinierten webhook von Grund auf:

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

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

Alle obligatorischen Eingabefelder sind mit einem roten Sternchen markiert.

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

Parameter Beschreibung
Parameter Geben Sie die webhook-Variablen als Attribut-Wert-Paare an.
Bei vorkonfigurierten webhooks variiert die Liste der Parameter je nach Dienst. Prüfen Sie die Datei Readme.md des webhook auf die Parameterbeschreibung.
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 documentation).
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 ein Funktionscode, der Parameter-Wert-Paare akzeptiert. Die Werte sollten mit der Methode JSON.parse() in JSON-Objekte umgewandelt werden, zum Beispiel: var params = JSON.parse(value);.

Der Code hat Zugriff auf alle Parameter; er kann HTTP-GET-, POST-, PUT- und DELETE-Anfragen ausführen, zusätzliche Methoden wie CONNECT, PATCH, HEAD, OPTIONS und TRACE unterstützen sowie HTTP-Header und den Anfrage-Body steuern.
Das Skript muss einen return-Operator enthalten, andernfalls ist es ungü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.

Wiederherstellungsereignisse (unabhängig davon, ob sie automatisch oder infolge eines manuellen Schließens erzeugt wurden) werden vom Server erstellt und enthalten aufgelöste Ereignis-Tags (einschließlich von Vorlagen, Hosts und Auslösern geerbter Tags). Webhook-Skripte werden ausgeführt, nachdem die Warnung erstellt wurde; daher werden von einem webhook-Skript zurückgegebene Tags erst nach der anfänglichen Erstellung der Warnung hinzugefügt und sind in den Makros {EVENT.TAGS} und {EVENT.RECOVERY.TAGS} der ursprünglichen Problemmeldung oder der unmittelbaren Wiederherstellungsmeldung nicht vorhanden.
Hinweis: Es wird empfohlen, lokale Variablen (z. B. var local = 1) anstelle globaler Variablen (z. B. global = 1) zu verwenden, um sicherzustellen, dass jedes Skript mit seinen eigenen Daten arbeitet, und um Kollisionen zwischen gleichzeitigen Aufrufen zu vermeiden (siehe known issues).

Siehe auch: Richtlinien für die webhook-Entwicklung, Beispiele für webhook-Skripte, Zusätzliche JavaScript-Objekte.
Timeout Zeitüberschreitung für die JavaScript-Ausführung (1-60s, Standard 30s).
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 zurückgegebene Tags: jira-id:prod-1234, responsible:John Smith, processed:<no value>
Eintrag im Ereignismenü einschließen Aktivieren Sie das Kontrollkästchen, um einen Eintrag im Ereignismenü einzuschließen, der auf ein erstelltes externes Ticket verweist.
Für jeden webhook, der aktiviert ist und bei dem dieses Kontrollkästchen markiert ist, wird ein Eintrag eingefügt. Beachten Sie, dass ein Eintrag nur dann eingefügt wird, wenn die Parameter Name des Menüeintrags und URL des Menüeintrags Makros vom Typ {EVENT.TAGS.<tag name>} enthalten und diese Makros aufgelöst werden können (d. h. das Ereignis hat diese Tags definiert).
Wenn diese Option markiert ist, sollte der webhook nicht zum Senden von Benachrichtigungen an verschiedene Benutzer verwendet werden (erwägen Sie stattdessen die Erstellung eines dedicated user) und nicht in mehreren Warnaktionen 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 obligatorisch, wenn Eintrag im Ereignismenü einschließen markiert 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 obligatorisch, wenn Eintrag im Ereignismenü einschließen markiert ist.

Siehe allgemeine Medientyp-Parameter für Details zur Konfiguration von Standardmeldungen und Optionen zur Warnungsverarbeitung.

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

Testen

So testen Sie einen konfigurierten webhook-Medientyp:

  1. Suchen Sie den entsprechenden 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 webhook-Parameterwerte 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 webhook bleiben unverändert.

Um Testprotokolleinträge des Medientyps anzuzeigen, ohne das Testfenster zu verlassen, klicken Sie auf Open log (ein neues Pop-up-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 bestehenden Benutzer zu oder erstellen Sie einen neuen Benutzer, der das webhook repräsentiert. Die Schritte zum Einrichten von Benutzermedien für einen bestehenden Benutzer, die für alle Medientypen gleich sind, werden auf der Seite Medientypen beschrieben.

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

  1. Nachdem Sie den webhook-Medientyp konfiguriert haben, gehen Sie 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. Gehen Sie im Benutzerprofil auf die Registerkarte Medien und fügen Sie ein webhook hinzu und geben Sie die erforderlichen Kontaktinformationen an. 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 Benachrichtigungen senden soll.

Fügen Sie bei der Konfiguration der Aktionsbenachrichtigung diesen Benutzer im Feld An Benutzer senden in den Vorgangsdetails 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.