4 Webhook

Przegląd

Typ nośnika webhook jest przydatny do wykonywania wywołań HTTP przy użyciu niestandardowego kodu JavaScript w celu łatwej integracji z zewnętrznym oprogramowaniem, takim jak systemy helpdesk, czaty lub komunikatory. Możesz wybrać import integracji dostarczonej przez Zabbix lub utworzyć własną integrację od podstaw.

Integracje

Dostępne są następujące integracje, umożliwiające użycie predefiniowanych typów mediów webhook do wysyłania powiadomień Zabbix do:

Oprócz usług wymienionych tutaj, Zabbix można zintegrować również z Spiceworks (webhook nie jest wymagany). Aby przekształcać powiadomienia Zabbix w zgłoszenia Spiceworks, utwórz typ mediów e-mail i w ustawieniach profilu wyznaczonego użytkownika Zabbix wprowadź adres e-mail helpdesku Spiceworks (np. help\@zabbix.on.spiceworks.com).

Konfiguracja

Aby rozpocząć korzystanie z integracji webhook:

  1. Znajdź wymagany plik .yaml w katalogu templates/media pobranej wersji Zabbix lub pobierz go z repozytorium Zabbix git repository.
  2. Zaimportuj plik do swojej instalacji Zabbix. Webhook pojawi się na liście typów mediów.
  3. Skonfiguruj webhook zgodnie z instrukcjami w pliku Readme.md (możesz kliknąć nazwę webhook powyżej, aby szybko przejść do Readme.md).

Aby utworzyć własny webhook od podstaw:

  1. Przejdź do Alerts > Media types.
  2. Kliknij Create media type.

Karta Media type zawiera różne atrybuty specyficzne dla tego typu mediów:

Wszystkie obowiązkowe pola wejściowe są oznaczone czerwoną gwiazdką.

Poniższe parametry są specyficzne dla typu mediów webhook:

Parameter Description
Parameters Określ zmienne webhook jako pary atrybut-wartość.
W przypadku wstępnie skonfigurowanych webhook lista parametrów różni się w zależności od usługi. Opis parametrów znajduje się w pliku Readme.md webhook.
W przypadku nowych webhook domyślnie uwzględniane są niektóre wspólne zmienne (URL:<empty>, HTTPProxy:<empty>, To:{ALERT.SENDTO}, Subject:{ALERT.SUBJECT}, Message:{ALERT.MESSAGE}); możesz je pozostawić lub usunąć.

Parametry webhook obsługują makra użytkownika, wszystkie makra obsługiwane w powiadomieniach o problemach oraz dodatkowo makra {ALERT.SENDTO}, {ALERT.SUBJECT} i {ALERT.MESSAGE}.

Jeśli określisz proxy HTTP, pole obsługuje tę samą funkcjonalność co pole HTTP proxy w konfiguracji pozycja. Ciąg proxy może być poprzedzony [scheme]://, aby określić, jaki rodzaj proxy jest używany (np. https, socks4, socks5; zobacz dokumentację).
Script Wprowadź kod JavaScript w edytorze modalnym, który otwiera się po kliknięciu w pole parametru lub ikonę ołówka obok niego. Ten kod wykona operację webhook.
Kod jest funkcją, która przyjmuje pary parametr - wartość. Wartości należy konwertować na obiekty JSON za pomocą metody JSON.parse(), na przykład: var params = JSON.parse(value);.

Kod ma dostęp do wszystkich parametrów, może wykonywać żądania HTTP GET, POST, PUT i DELETE, obsługuje dodatkowe metody, takie jak CONNECT, PATCH, HEAD, OPTIONS i TRACE, oraz ma kontrolę nad nagłówkami HTTP i treścią żądania.
Skrypt musi zawierać operator return, w przeciwnym razie nie będzie poprawny. Może zwrócić status OK wraz z opcjonalną listą tagów i wartości tagów (zobacz opcję Process tags) albo ciąg błędu.

Zdarzenia odzyskania (zarówno generowane automatycznie, jak i w wyniku ręcznego zamknięcia) są tworzone przez serwer i zawierają tagi rozwiązanych zdarzeń (w tym tagi odziedziczone z szablonów, hostów i wyzwalaczy). Skrypty webhook są wykonywane po utworzeniu alertu; dlatego tagi zwracane przez skrypt webhook są dodawane dopiero po początkowym utworzeniu alertu i nie będą obecne w makrach {EVENT.TAGS} ani {EVENT.RECOVERY.TAGS} początkowej wiadomości o problemie lub natychmiastowej wiadomości o odzyskaniu.
Uwaga: Zaleca się używanie zmiennych lokalnych (np. var local = 1) zamiast globalnych (np. global = 1), aby zapewnić, że każdy skrypt działa na własnych danych i uniknąć kolizji między jednoczesnymi wywołaniami (zobacz znane problemy).

Zobacz także: Webhook development guidelines, Webhook script examples, Additional JavaScript objects.
Timeout Limit czasu wykonania JavaScript (1-60 s, domyślnie 30 s).
Obsługiwane są sufiksy czasu, np. 30s, 1m.
Process tags Zaznacz pole wyboru, aby przetwarzać zwrócone wartości właściwości JSON jako tagi. Tagi te są dodawane do wszystkich istniejących tagów problemu.
Pamiętaj, że podczas korzystania z webhook tags webhook musi zwrócić obiekt JSON zawierający co najmniej pusty obiekt tags: var result = {tags: {}};
Przykłady tagów, które mogą zostać zwrócone: jira-id:prod-1234, responsible:John Smith, processed:<no value>
Include event menu entry Zaznacz pole wyboru, aby uwzględnić wpis w menu zdarzenia prowadzący do utworzonego zewnętrznego zgłoszenia.
Wpis zostanie dodany dla każdego włączonego webhook, dla którego zaznaczono to pole wyboru. Pamiętaj, że jeśli parametry Menu entry name i Menu entry URL zawierają jakiekolwiek makra {EVENT.TAGS.<tag name>}, wpis zostanie dodany tylko wtedy, gdy makra te będzie można rozwiązać (to znaczy, gdy zdarzenie ma zdefiniowane te tagi).
Jeśli opcja jest zaznaczona, webhook nie powinien być używany do wysyłania powiadomień do różnych użytkowników (rozważ utworzenie dedykowanego użytkownika zamiast tego) i nie powinien być używany w wielu akcjach alertów dla pojedynczego zdarzenia problemu.
Menu entry name Określ nazwę wpisu menu.
Obsługiwane jest makro {EVENT.TAGS.<tag name>}.
To pole jest obowiązkowe tylko wtedy, gdy zaznaczono Include event menu entry.
Menu entry URL Określ docelowy adres URL wpisu menu.
Obsługiwane jest makro {EVENT.TAGS.<tag name>}.
To pole jest obowiązkowe tylko wtedy, gdy zaznaczono Include event menu entry.

Szczegóły dotyczące konfiguracji domyślnych wiadomości i opcji przetwarzania alertów znajdziesz w sekcji common media type parameters.

Nawet jeśli webhook nie używa domyślnych wiadomości, szablony wiadomości dla typów operacji używanych przez ten webhook nadal muszą być zdefiniowane.

Testowanie

Aby przetestować skonfigurowany typ mediów webhook:

  1. Znajdź odpowiedni webhook na liście typów mediów.
  2. Kliknij Test w ostatniej kolumnie listy (otworzy się okno testowe).
  3. W razie potrzeby edytuj wartości parametrów webhook. Zastąp makra przykładowymi wartościami; w przeciwnym razie makra nie zostaną rozwiązane i test zakończy się niepowodzeniem.
  4. Kliknij Test.

Zastępowanie lub usuwanie wartości w oknie testowym wpływa tylko na procedurę testową, rzeczywiste wartości atrybutów webhook pozostaną bez zmian.

Aby wyświetlić wpisy dziennika testu typu mediów bez opuszczania okna testowego, kliknij Open log (otworzy się nowe okno podręczne).

Jeśli test webhooka zakończy się powodzeniem:

  • Wyświetlany jest komunikat „Media type test successful.”.
  • Odpowiedź serwera pojawia się w szarym polu Response.
  • Typ odpowiedzi (JSON lub String) jest określony poniżej pola Response.

Jeśli test webhooka zakończy się niepowodzeniem:

  • Wyświetlany jest komunikat „Test typu nośnika nie powiódł się.”, po którym podawane są dodatkowe szczegóły dotyczące błędu.

Media użytkownika

Po skonfigurowaniu typu mediów przejdź do sekcji Users > Users i przypisz media webhook do istniejącego użytkownika lub utwórz nowego użytkownika reprezentującego webhook. Kroki konfiguracji mediów użytkownika dla istniejącego użytkownika, wspólne dla wszystkich typów mediów, opisano na stronie Typy mediów.

Jeśli webhook używa tagów do przechowywania ID zgłoszenia\wiadomości, unikaj przypisywania tego samego webhooka jako mediów różnym użytkownikom, ponieważ może to powodować błędy webhooka (dotyczy to większości webhooków korzystających z opcji Include event menu entry). W takim przypadku zalecaną praktyką jest utworzenie dedykowanego użytkownika reprezentującego webhook:

  1. Po skonfigurowaniu typu mediów webhook przejdź do sekcji Users > Users i utwórz dedykowanego użytkownika Zabbix reprezentującego webhook — na przykład o nazwie użytkownika Slack dla webhooka Slack. Wszystkie ustawienia, z wyjątkiem mediów, można pozostawić domyślne, ponieważ ten użytkownik nie będzie logował się do Zabbix.
  2. W profilu użytkownika przejdź do zakładki Media i dodaj webhook, podając wymagane informacje kontaktowe. Jeśli webhook nie używa pola Send to, wprowadź dowolną kombinację obsługiwanych znaków, aby obejść wymagania walidacji.
  3. Przyznaj temu użytkownikowi co najmniej uprawnienia do odczytu permissions do wszystkich hostów, dla których powinien wysyłać alerty.

Podczas konfigurowania akcji alertów dodaj tego użytkownika w polu Send to users w szczegółach operacji — spowoduje to, że Zabbix będzie używać webhooka do powiadomień z tej akcji.

Konfigurowanie akcji alertów

Akcje określają, które powiadomienia mają być wysyłane za pośrednictwem webhooka. Kroki konfigurowania akcji z użyciem webhooków są takie same jak dla wszystkich innych typów mediów, z następującymi wyjątkami:

  • Jeśli webhook używa tagów webhooka do przechowywania ID zgłoszenia\wiadomości oraz obsługi operacji aktualizacji\rozwiązania, należy unikać używania tego samego webhooka w wielu akcjach alertów dla pojedynczego zdarzenia problemu. Jeśli {EVENT.TAGS.<tag name>} istnieje i zostanie zaktualizowane w webhooku, jego wynikowa wartość będzie niezdefiniowana. Aby tego uniknąć, użyj w webhooku nowej nazwy tagu do przechowywania zaktualizowanych wartości. Dotyczy to webhooków Jira, Jira Service Desk, Mattermost, Opsgenie, OTRS, Redmine, ServiceNow, Slack, Zammad i Zendesk dostarczanych przez Zabbix oraz większości webhooków wykorzystujących opcję Include event menu entry. Należy jednak pamiętać, że pojedynczy webhook może być używany w wielu operacjach lub krokach eskalacji tej samej akcji, a także w różnych akcjach, które nie zostaną wyzwolone przez to samo zdarzenie problemu z powodu różnych warunków.
  • W przypadku używania webhooka w akcjach dla zdarzeń wewnętrznych należy zaznaczyć pole wyboru Custom message i zdefiniować własną wiadomość w konfiguracji operacji akcji. W przeciwnym razie powiadomienie nie zostanie wysłane.