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 wprowadź adres e-mail helpdesku Spiceworks (np. help\@zabbix.on.spiceworks.com) w ustawieniach profilu wyznaczonego użytkownika Zabbix.

Konfiguracja

Aby rozpocząć korzystanie z integracji webhook:

  1. Odszukaj 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ę webhooka powyżej, aby szybko przejść do pliku Readme.md).

Aby utworzyć własny webhook od podstaw:

  1. Przejdź do Alerty > Typy mediów.
  2. Kliknij Utwórz typ mediów.

Zakładka Typ mediów 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:

Parametr Opis
Parametry 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 znajdziesz w pliku Readme.md webhooka.
W przypadku nowych webhooków domyślnie uwzględnionych jest kilka wspólnych zmiennych (URL:<empty>, HTTPProxy:<empty>, To:{ALERT.SENDTO}, Subject:{ALERT.SUBJECT}, Message:{ALERT.MESSAGE}); możesz je zachować 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 proxy HTTP, pole obsługuje tę samą funkcjonalność co pole HTTP proxy w konfiguracji pozycji. Ciąg proxy może być poprzedzony prefiksem [scheme]://, aby określić, jaki rodzaj proxy jest używany (np. https, socks4, socks5; zobacz documentation).
Script Wprowadź kod JavaScript w modalnym edytorze, który otwiera się po kliknięciu w pole parametru lub ikonę ołówka obok niego. Ten kod wykona operację webhooka.
Skrypt jest kodem funkcji, który przyjmuje pary parametr-wartość. Wartości należy przekonwertować 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 zapewnia kontrolę nad 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 odzyskania (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 dziedziczone z szablonów, hostów i wyzwalaczy). Skrypty webhook są wykonywane po utworzeniu alertu; dlatego tagi zwrócone przez skrypt webhooka są dodawane dopiero po początkowym utworzeniu alertu i nie będą obecne w makrach {EVENT.TAGS} oraz {EVENT.RECOVERY.TAGS} początkowej wiadomości o problemie ani wiadomości o natychmiastowym odzyskaniu.
Uwaga: Zaleca się używanie zmiennych lokalnych (np. var local = 1) zamiast globalnych (np. global = 1), aby zapewnić, że każdy skrypt operuje na własnych danych, i uniknąć kolizji między równoczesnymi wywołaniami (zobacz known issues).

Zobacz także: Webhook development guidelines, Przykłady skryptów webhook, Dodatkowe obiekty JavaScript.
Timeout Limit czasu wykonania JavaScript (1-60s, domyślnie 30s).
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.
Zwróć uwagę, że przy użyciu tagów webhook 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 webhooka, który jest włączony i ma zaznaczone to pole wyboru. Zwróć uwagę, że jeśli parametry Menu entry name i Menu entry URL zawierają jakiekolwiek makra {EVENT.TAGS.<tag name>}, wpis zostanie dodany tylko wtedy, gdy te makra 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ż zamiast tego 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 bazowy 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.

Zobacz wspólne parametry typu mediów, aby uzyskać szczegółowe informacje o konfigurowaniu domyślnych wiadomości i opcji przetwarzania alertów.

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 Użytkownicy > Użytkownicy 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 identyfikatora 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 Dołącz wpis menu zdarzenia). W takim przypadku zalecaną praktyką jest utworzenie dedykowanego użytkownika reprezentującego webhook:

  1. Po skonfigurowaniu typu mediów webhook przejdź do sekcji Użytkownicy > Użytkownicy i utwórz dedykowanego użytkownika Zabbix reprezentującego webhook — na przykład z nazwą 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 Wyślij do, wprowadź dowolną kombinację obsługiwanych znaków, aby obejść wymagania walidacji.
  3. Przyznaj temu użytkownikowi co najmniej uprawnienia do odczytu do wszystkich hostów, dla których ma wysyłać alerty, zgodnie z uprawnieniami.

Podczas konfigurowania akcji alertu dodaj tego użytkownika w polu Wyślij do użytkowników w szczegółach operacji — poinformuje to Zabbix, aby 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.