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 korzystanie z predefiniowanych typów mediów webhook do przesyłania powiadomień Zabbix do:

Oprócz usług wymienionych tutaj, Zabbix można zintegrować z Spiceworks (nie jest wymagany webhook). Aby przekształcić powiadomienia Zabbix w zgłoszenia Spiceworks, utwórz typ mediów e-mail i wpisz adres e-mail helpdesku Spiceworks (np. [email protected]) w ustawieniach profilu wskazanego użytkownika Zabbix.

Konfiguracja

Aby rozpocząć korzystanie z integracji webhook:

  1. Znajdź wymagany plik .yaml w katalogu templates/media pobranej wersji Zabbix lub pobierz go z repozytorium git Zabbix.
  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 otworzyć plik Readme.md).

Aby utworzyć niestandardowy webhook od podstaw:

  1. Przejdź do Alerty > Typy mediów.
  2. Kliknij Utwórz typ mediów.
  3. Wprowadź parametry typu mediów webhook w formularzu.

Karta Typ mediów zawiera różne atrybuty właściwe dla tego typu mediów:

Wszystkie wymagane pola wejściowe są oznaczone czerwoną gwiazdką.

Poniższe parametry są właściwe dla typu mediów webhook:

Parametr Opis
Parametry 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 znajdziesz w pliku Readme.md webhook.
W przypadku nowych webhook domyślnie uwzględniono kilka typowych zmiennych (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, a dodatkowo makra {ALERT.SENDTO}, {ALERT.SUBJECT} i {ALERT.MESSAGE}.

Jeśli określisz proxy HTTP, pole obsługuje taką samą funkcjonalność jak pole proxy HTTP w konfiguracji pozycji. Ciąg proxy może być poprzedzony przez [scheme]://, aby określić używany rodzaj proxy (np. https, socks4, socks5; zobacz dokumentację).
Skrypt Wprowadź kod JavaScript w edytorze modalnym, który otwiera się po kliknięciu pola parametru lub ikony ołówka obok niego. Kod ten wykona operację webhook.
Skrypt jest kodem funkcji, 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ługiwać dodatkowe metody, takie jak CONNECT, PATCH, HEAD, OPTIONS i TRACE, a także zarządzać nagłówkami HTTP i treścią żądania.
Skrypt musi zawierać operator return, w przeciwnym razie nie będzie prawidłowy. Może zwracać status OK wraz z opcjonalną listą tagów i wartości tagów (zobacz opcję Przetwarzaj tagi) albo ciąg błędu.

Zdarzenia odtworzenia (niezależnie od tego, czy zostały wygenerowane automatycznie, czy w wyniku ręcznego zamknięcia) są tworzone przez serwer i zawierają rozwiązane tagi zdarzenia (w tym tagi odziedziczone z szablonów, hostów i wyzwalaczy). Skrypty webhook są wykonywane po utworzeniu alertu, dlatego tagi zwrócone przez skrypt webhook są dodawane dopiero po początkowym utworzeniu alertu i nie będą obecne w makrach {EVENT.TAGS} i {EVENT.RECOVERY.TAGS} początkowego komunikatu o problemie ani bezpośredniego komunikatu o odtworzeniu.
Uwaga: Zaleca się używanie zmiennych lokalnych (np. var local = 1) zamiast zmiennych globalnych (np. global = 1), aby zapewnić, że każdy skrypt działa na własnych danych, oraz uniknąć kolizji między jednoczesnymi wywołaniami (zobacz znane problemy).

Zobacz także: [Wytyczne dotyczące tworzenia webhook] (https://www.zabbix.com/documentation/guidelines/en/webhooks), Przykłady skryptów webhook, Dodatkowe obiekty JavaScript.
Limit czasu Limit czasu wykonywania JavaScript (1-60 s, domyślnie 30 s).
Obsługiwane są przyrostki czasu (np. 30s, 1m).
Przetwarzaj tagi Zaznacz pole wyboru, aby przetwarzać wartości zwróconych właściwości JSON jako tagi. Tagi te są dodawane do wszystkich istniejących tagów problemu.
Pamiętaj, że w przypadku używania tagów webhook webhook musi zwracać obiekt JSON zawierający co najmniej pusty obiekt tagów: var result = {tags: {}};
Przykłady tagów, które mogą zostać zwrócone: jira-id:prod-1234, responsible:John Smith, processed:<no value>
Uwzględnij pozycję w menu zdarzenia Zaznacz pole wyboru, aby uwzględnić pozycję w menu zdarzenia zawierającą odnośnik do utworzonego zewnętrznego zgłoszenia.
Pozycja zostanie uwzględniona dla każdego włączonego webhook, dla którego zaznaczono to pole wyboru. Pamiętaj, że jeśli parametry Nazwa pozycji menu i URL pozycji menu zawierają makra {EVENT.TAGS.<tag name>}, pozycja zostanie uwzględniona tylko wtedy, gdy te makra mogą zostać rozwiązane (czyli gdy dla zdarzenia zdefiniowano 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) ani używany w wielu działaniach alertów dla pojedynczego zdarzenia problemu.
Nazwa pozycji menu Określ nazwę pozycji menu.
Obsługiwane jest makro {EVENT.TAGS.<tag name>}.
To pole jest wymagane tylko wtedy, gdy zaznaczono opcję Uwzględnij pozycję w menu zdarzenia.
URL pozycji menu Określ docelowy URL pozycji menu.
Obsługiwane jest makro {EVENT.TAGS.<tag name>}.
To pole jest wymagane tylko wtedy, gdy zaznaczono opcję Uwzględnij pozycję w menu zdarzenia.

Szczegółowe informacje dotyczące konfigurowania domyślnych komunikatów i opcji przetwarzania alertów znajdziesz w sekcji wspólne parametry typu mediów.

Nawet jeśli webhook nie korzysta z domyślnych komunikatów, nadal należy zdefiniować szablony komunikatów dla typów operacji używanych przez ten webhook.

Testowanie

Aby przetestować skonfigurowany typ nośnika webhook:

  1. Znajdź odpowiedni webhook na liście typów nośników.
  2. Kliknij Test w ostatniej kolumnie listy (otworzy się okno testowania).
  3. W razie potrzeby edytuj wartości parametrów webhooka.
    Zastąp makra przykładowymi wartościami. W przeciwnym razie makra nie zostaną rozwinięte, a test zakończy się niepowodzeniem.
  4. Kliknij Test.

Zastępowanie lub usuwanie wartości w oknie testowania wpływa wyłącznie na procedurę testową; rzeczywiste wartości atrybutów webhooka pozostaną niezmienione.

Aby wyświetlić wpisy dziennika testu typu nośnika bez opuszczania okna testowania, 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 nośnika przejdź do sekcji Users > Users i przypisz nośnik webhook do istniejącego użytkownika lub utwórz nowego użytkownika reprezentującego webhook.

Czynności związane z konfigurowaniem mediów użytkownika dla istniejącego użytkownika, wspólne dla wszystkich typów nośników, opisano na stronie Media types.

Jeśli webhook używa znaczników do przechowywania identyfikatora zgłoszenia\wiadomości, unikaj przypisywania tego samego webhooka jako nośnika do różnych użytkowników, 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 najlepszym rozwiązaniem jest utworzenie dedykowanego użytkownika reprezentującego webhook:

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

Podczas konfigurowania akcji alertu dodaj tego użytkownika w polu Send to users w sekcji Operation details — spowoduje to, że Zabbix będzie używać webhooka do wysyłania powiadomień z tej akcji.

Konfigurowanie akcji alertów

Akcje określają, które powiadomienia powinny być wysyłane za pośrednictwem webhooka. Kroki dotyczące 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 identyfikatora zgłoszenia/wiadomości i obsługi operacji aktualizacji/rozwiązania, unikaj używania tego samego webhooka w wielu akcjach alertów dla pojedynczego zdarzenia problemu. Jeśli {EVENT.TAGS.<tag name>} istnieje i zostanie zaktualizowany w webhooku, jego wynikowa wartość będzie niezdefiniowana. Aby tego uniknąć, użyj nowej nazwy tagu w webhooku 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ą wywołane przez to samo zdarzenie problemu z powodu różnych warunków.
  • Podczas używania webhooka w akcjach dla zdarzeń wewnętrznych upewnij się, że zaznaczono pole Custom message i zdefiniowano niestandardową wiadomość w konfiguracji operacji akcji. W przeciwnym razie powiadomienie nie zostanie wysłane.