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ł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 wybranego 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.

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ów i wartości.
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 danego 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 tę samą funkcjonalność co 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. Ten kod 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 sterować 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.

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ątkowym komunikacie o problemie ani w komunikatach o przywróceniu, ponieważ skrypt nie zdążył się jeszcze wykonać.
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 i 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ć 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 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 zwracanych tagów: 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 makra te będzie można rozwiązać (czyli gdy zdarzenie będzie miało 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) 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 typów mediów.

Nawet jeśli webhook nie używa domyślnych komunikatów, szablony komunikatów 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.