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 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łcać powiadomienia Zabbix w zgłoszenia Spiceworks, utwórz typ mediów e-mail i wpisz adres e-mail helpdesku Spiceworks (np. help\@zabbix.on.spiceworks.com) w ustawieniach profilu wybranego użytkownika Zabbix.

Konfiguracja

Aby rozpocząć korzystanie z integracji webhook:

  1. Znajdź wymagany plik .yaml w katalogu templates/media pobranej wersji Zabbixa lub pobierz go z repozytorium Zabbixa git repository.
  2. Zaimportuj plik do swojej instalacji Zabbixa. Webhook pojawi się na liście typów mediów.
  3. Skonfiguruj webhook zgodnie z instrukcjami w pliku Readme.md (możesz kliknąć nazwę webhooka 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ą.

Następujące parametry są specyficzne dla typu mediów webhook:

Parameter Description
Parameters Określ zmienne webhooka jako pary atrybut-wartość.
W przypadku wstępnie skonfigurowanych webhooków lista parametrów różni się w zależności od usługi. Opis parametrów znajduje się w pliku Readme.md webhooka.
W przypadku nowych webhooków 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 webhooka 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 serwer proxy HTTP, pole obsługuje tę samą funkcjonalność co pole HTTP proxy w konfiguracji pozycji. 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 pola parametru lub ikony ołówka obok niego. Ten kod wykona operację webhooka.
Skrypt jest kodem funkcji, który 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 zwracać status OK wraz z opcjonalną listą tagów i wartości tagów (zobacz opcję Process tags) albo ciąg błędu.

Pamiętaj, że skrypt jest wykonywany dopiero po utworzeniu alertu. Jeśli skrypt jest skonfigurowany tak, aby zwracał i przetwarzał tagi, tagi te nie zostaną rozwiązane w makrach {EVENT.TAGS} i {EVENT.RECOVERY.TAGS} w początkowej wiadomości o problemie oraz w wiadomościach odzyskiwania, ponieważ skrypt nie zdążył jeszcze zostać uruchomiony.
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 równoczesnymi 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 używania 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 dodać wpis w menu zdarzenia prowadzący do utworzonego zewnętrznego zgłoszenia.
Wpis zostanie dodany dla każdego włączonego webhooka, dla którego zaznaczono to pole. 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 mogą zostać rozwiązane (to znaczy, gdy zdarzenie ma zdefiniowane te tagi).
Jeśli pole jest zaznaczone, webhook nie powinien być używany do wysyłania powiadomień do różnych użytkowników (rozważ utworzenie dedykowanego użytkownika) 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 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ąpienie lub usunięcie wartości w oknie testowania wpływa tylko na procedurę testową; rzeczywiste wartości atrybutów webhooka pozostaną bez zmian.

Aby wyświetlić wpisy dziennika testu typu nośnika bez opuszczania okna testowego, kliknij Open log (otworzy się nowe wyskakujące okno).

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.