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 mit Spiceworks integriert werden (dafür 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 Zabbix-Git-Repository herunter.
  2. Importieren Sie die Datei in Ihre Zabbix-Installation. Die webhook wird in der Liste der Medientypen angezeigt.
  3. Konfigurieren Sie die webhook gemäß den Anweisungen in der Datei Readme.md (Sie können oben auf den Namen einer webhook klicken, um schnell auf Readme.md zuzugreifen).

So erstellen Sie eine benutzerdefinierte webhook von Grund auf:

  1. Gehen Sie zu Alarme > Medientypen.
  2. Klicken Sie auf Medientyp erstellen.
  3. Geben Sie die Parameter des webhook-Medientyps im Formular ein.

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 Readme.md-Datei der webhook.
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]:// beginnen, 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 ein Funktionscode, der 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-Anforderungen ausführen, zusätzliche Methoden wie CONNECT, PATCH, HEAD, OPTIONS und TRACE unterstützen und HTTP-Header sowie den Anforderungstext 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 der Alarm erstellt wurde. Daher werden von einem webhook-Skript zurückgegebene Tags erst nach der ursprünglichen Alarmerstellung 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, 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 bei Verwendung von webhook-Tags die webhook 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>
Ereignismenüeintrag einschließen Aktivieren Sie das Kontrollkästchen, um im Ereignismenü einen Eintrag einzuschließen, der auf ein erstelltes externes Ticket verweist.
Für jede aktivierte webhook, bei der 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 die 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 erforderlich, 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 erforderlich, wenn Ereignismenüeintrag einschließen aktiviert ist.

Unter allgemeine Medientypparameter finden Sie Einzelheiten zur Konfiguration von Standardnachrichten und Optionen für die Alarmverarbeitung.

Auch wenn eine webhook keine Standardnachrichten verwendet, müssen Nachrichtenvorlagen für die von dieser webhook verwendeten Aktionstypen weiterhin 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 Werte der webhook-Parameter nach Bedarf.
    Ersetzen Sie Makros durch Beispielwerte. Andernfalls werden die 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 die Testprotokolleinträge des Medientyps anzuzeigen, ohne das Testfenster zu verlassen, klicken Sie auf Protokoll öffnen (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

Nachdem der Medientyp konfiguriert wurde, wechseln 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 gelten, werden auf der Seite Medientypen beschrieben.

Wenn ein webhook Tags zum Speichern der Ticket\Nachrichten-ID verwendet, vermeiden Sie es, dasselbe webhook verschiedenen Benutzern als Medium zuzuweisen, da dies zu webhook-Fehlern führen kann (gilt für die Mehrheit der Webhooks, die die Option Include event menu entry 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, wechseln 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 dem Medium 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, indem Sie die erforderlichen Kontaktinformationen angeben. Wenn das webhook kein Feld Send to verwendet, geben Sie eine beliebige Kombination unterstützter Zeichen ein, um die Validierungsanforderungen zu umgehen.
  3. Gewähren Sie diesem Benutzer mindestens Leseberechtigungen für alle Hosts, für die er die Alarme senden soll, unter Berechtigungen.

Fügen Sie beim Konfigurieren der Alarmauslösung diesen Benutzer im Feld Send to users unter den Operationsdetails hinzu - dadurch wird Zabbix angewiesen, das webhook für Benachrichtigungen aus dieser Aktion zu verwenden.

Konfigurieren von Alarmaktionen

Aktionen bestimmen, welche Benachrichtigungen über das webhook gesendet werden sollen. Die Schritte zum Konfigurieren von Aktionen, die webhooks betreffen, sind mit Ausnahme der folgenden Punkte für alle anderen Medientypen gleich:

  • Wenn ein webhook webhook-Tags verwendet, um Ticket\Nachrichten-ID zu speichern und Update- bzw. Resolve-Operationen zu verarbeiten, vermeiden Sie die Verwendung desselben webhooks in mehreren Alarmaktionen für ein einzelnes Problemereignis. Wenn {EVENT.TAGS.<tag name>} vorhanden ist und im webhook aktualisiert wird, ist der resultierende 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 für 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 verwendet werden kann, ebenso wie in verschiedenen Aktionen, 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 definieren. Andernfalls wird keine Benachrichtigung gesendet.