webhook

Panoramica

Il tipo di supporto webhook è utile per effettuare chiamate HTTP utilizzando codice JavaScript personalizzato per un'integrazione semplice con software esterni come sistemi di helpdesk, chat o messenger. È possibile scegliere di importare un'integrazione fornita da Zabbix oppure creare un'integrazione personalizzata da zero.

Integrazioni

Le seguenti integrazioni sono disponibili e consentono di usare tipi di media webhook predefiniti per inviare notifiche Zabbix a:

Oltre ai servizi elencati qui, Zabbix può essere integrato con Spiceworks (non è richiesto alcun webhook). Per convertire le notifiche Zabbix in ticket Spiceworks, crea un tipo di media email e inserisci l'indirizzo email dell'helpdesk Spiceworks (ad esempio, [email protected]) nelle impostazioni del profilo di un utente Zabbix designato.

Configurazione

Per iniziare a utilizzare un'integrazione webhook:

  1. Individuare il file .yaml richiesto nella directory templates/media della versione di Zabbix scaricata oppure scaricarlo dal repository git di Zabbix.
  2. Importare il file nell'installazione di Zabbix. Il webhook verrà visualizzato nell'elenco dei tipi di supporto.
  3. Configurare il webhook seguendo le istruzioni nel file Readme.md (è possibile fare clic sul nome di un webhook qui sopra per accedere rapidamente al file Readme.md).

Per creare un webhook personalizzato da zero:

  1. Accedere a Avvisi > Tipi di supporto.
  2. Fare clic su Crea tipo di supporto.
  3. Inserire i parametri del tipo di supporto webhook nel modulo.

La scheda Tipo di supporto contiene vari attributi specifici per questo tipo di supporto:

Tutti i campi di input obbligatori sono contrassegnati da un asterisco rosso.

I seguenti parametri sono specifici per il tipo di supporto webhook:

Parametro Descrizione
Parametri Specificare le variabili del webhook come coppie attributo e valore.
Per i webhook preconfigurati, l'elenco dei parametri varia in base al servizio. Consultare il file Readme.md del webhook per la descrizione dei parametri.
Per i nuovi webhook, diverse variabili comuni sono incluse per impostazione predefinita (URL:<empty>, HTTPProxy:<empty>, To:{ALERT.SENDTO}, Subject:{ALERT.SUBJECT}, Message:{ALERT.MESSAGE}); è possibile mantenerle o rimuoverle.

I parametri del webhook supportano le macro utente, tutte le macro supportate nelle notifiche dei problemi e, inoltre, le macro {ALERT.SENDTO}, {ALERT.SUBJECT} e {ALERT.MESSAGE}.

Se si specifica un proxy HTTP, il campo supporta le stesse funzionalità del campo Proxy HTTP nella configurazione dell'item. La stringa del proxy può essere preceduta da [scheme]:// per specificare il tipo di proxy utilizzato (ad esempio https, socks4, socks5; vedere la documentazione).
Script Inserire il codice JavaScript nell'editor modale che si apre facendo clic nel campo del parametro o sull'icona a forma di matita accanto a esso. Questo codice eseguirà l'operazione del webhook.
Lo script è una funzione che accetta coppie parametro-valore. I valori devono essere convertiti in oggetti JSON utilizzando il metodo JSON.parse(), ad esempio: var params = JSON.parse(value);.

Il codice ha accesso a tutti i parametri, può eseguire richieste HTTP GET, POST, PUT e DELETE, supportare metodi aggiuntivi come CONNECT, PATCH, HEAD, OPTIONS e TRACE e gestire le intestazioni HTTP e il corpo della richiesta.
Lo script deve contenere un operatore return, altrimenti non sarà valido. Può restituire lo stato OK insieme a un elenco facoltativo di tag e valori dei tag (vedere l'opzione Elabora tag) oppure una stringa di errore.

Gli eventi di ripristino (generati automaticamente o in seguito a una chiusura manuale) vengono creati dal server e includono i tag dell'evento risolto, compresi quelli ereditati da template, host e trigger. Gli script webhook vengono eseguiti dopo la creazione dell'avviso; pertanto, i tag restituiti da uno script webhook vengono aggiunti solo dopo la creazione iniziale dell'avviso e non saranno presenti nelle macro {EVENT.TAGS} e {EVENT.RECOVERY.TAGS} del messaggio iniziale del problema o del messaggio di ripristino immediato.
Nota: si consiglia di utilizzare variabili locali (ad esempio var local = 1) invece di variabili globali (ad esempio global = 1) per garantire che ogni script operi sui propri dati ed evitare conflitti tra chiamate simultanee (vedere i problemi noti).

Vedere anche: Linee guida per lo sviluppo dei webhook, Esempi di script webhook, Oggetti JavaScript aggiuntivi.
Timeout Timeout di esecuzione JavaScript (1-60 s, valore predefinito 30 s).
Sono supportati i suffissi temporali (ad esempio 30s, 1m).
Elabora tag Selezionare la casella per elaborare i valori delle proprietà JSON restituiti come tag. Questi tag vengono aggiunti ai tag esistenti del problema.
Quando si utilizzano i tag webhook, il webhook deve restituire un oggetto JSON contenente almeno un oggetto tags vuoto: var result = {tags: {}};
Esempi di tag che possono essere restituiti: jira-id:prod-1234, responsible:John Smith, processed:<no value>
Includi voce nel menu degli eventi Selezionare la casella per includere nel menu degli eventi una voce che rimanda a un ticket esterno creato.
Verrà inclusa una voce per ogni webhook abilitato con questa casella selezionata. Se i parametri Nome voce di menu e URL voce di menu contengono macro {EVENT.TAGS.<tag name>}, la voce verrà inclusa solo se tali macro possono essere risolte, ovvero se l'evento ha questi tag definiti.
Se selezionata, il webhook non deve essere utilizzato per inviare notifiche a utenti diversi (valutare la creazione di un utente dedicato) e non deve essere utilizzato in più azioni di avviso per un singolo evento problema.
Nome voce di menu Specificare il nome della voce di menu.
La macro {EVENT.TAGS.<tag name>} è supportata.
Questo campo è obbligatorio solo se è selezionata l'opzione Includi voce nel menu degli eventi.
URL voce di menu Specificare l'URL sottostante della voce di menu.
La macro {EVENT.TAGS.<tag name>} è supportata.
Questo campo è obbligatorio solo se è selezionata l'opzione Includi voce nel menu degli eventi.

Per informazioni dettagliate sulla configurazione dei messaggi predefiniti e delle opzioni di elaborazione degli avvisi, vedere i parametri comuni dei tipi di supporto.

Anche se un webhook non utilizza messaggi predefiniti, è comunque necessario definire i template dei messaggi per i tipi di operazione utilizzati da questo webhook.

Test

Per testare un tipo di supporto webhook configurato:

  1. Individuare il webhook pertinente nell'elenco dei tipi di supporto.
  2. Fare clic su Test nell'ultima colonna dell'elenco (si aprirà una finestra di test).
  3. Modificare i valori dei parametri del webhook secondo necessità.
    Sostituire le macro con valori di esempio; in caso contrario, le macro non verranno risolte e il test avrà esito negativo.
  4. Fare clic su Test.

La sostituzione o l'eliminazione dei valori nella finestra di test influisce solo sulla procedura di test; i valori effettivi degli attributi del webhook rimarranno invariati.

Per visualizzare le voci del registro dei test del tipo di supporto senza uscire dalla finestra di test, fare clic su Apri registro (si aprirà una nuova finestra pop-up).

Se il test del webhook ha esito positivo:

  • viene visualizzato il messaggio "Media type test successful.".
  • la risposta del server appare nel campo grigio Response.
  • il tipo di risposta (JSON o String) è specificato sotto il campo Response.

Se il test del webhook fallisce:

  • viene visualizzato il messaggio "Media type test failed.", seguito da ulteriori dettagli sull'errore.

Media dell'utente

Una volta configurato il tipo di media, accedere alla sezione Users > Users e assegnare il media webhook a un utente esistente oppure creare un nuovo utente che rappresenti il webhook. I passaggi per configurare il media dell'utente esistente, comuni a tutti i tipi di media, sono descritti nella pagina Media types.

Se un webhook utilizza i tag per memorizzare l'ID del ticket\messaggio, evitare di assegnare lo stesso webhook come media a utenti diversi, poiché ciò potrebbe causare errori del webhook (vale per la maggior parte dei webhook che utilizzano l'opzione Include event menu entry). In questo caso, è consigliabile creare un utente dedicato che rappresenti il webhook:

  1. Dopo aver configurato il tipo di media webhook, accedere alla sezione Users > Users e creare un utente Zabbix dedicato che rappresenti il webhook, ad esempio con il nome utente Slack per il webhook Slack. Tutte le impostazioni, ad eccezione del media, possono essere lasciate ai valori predefiniti, poiché questo utente non accederà a Zabbix.
  2. Nel profilo dell'utente, accedere alla scheda Media e aggiungere un webhook con le informazioni di contatto richieste. Se il webhook non utilizza un campo Send to, inserire una combinazione qualsiasi di caratteri supportati per soddisfare i requisiti di convalida.
  3. Concedere a questo utente almeno autorizzazioni di lettura per tutti gli host per i quali deve inviare gli avvisi.

Quando si configura un'azione di avviso, aggiungere questo utente nel campo Send to users nei dettagli dell'operazione: in questo modo si indicherà a Zabbix di utilizzare il webhook per le notifiche generate da questa azione.

Configurazione delle azioni di allerta

Le azioni determinano quali notifiche devono essere inviate tramite il webhook. I passaggi per configurare le azioni che coinvolgono i webhook sono gli stessi di tutti gli altri tipi di media, con queste eccezioni:

  • Se un webhook usa i tag del webhook per memorizzare l'ID del ticket\messaggio e gestire le operazioni di aggiornamento\risoluzione, evita di usare lo stesso webhook in più azioni di allerta per un singolo evento di problema. Se {EVENT.TAGS.<tag name>} esiste e viene aggiornato nel webhook, il suo valore risultante sarà indefinito. Per evitare questo, usa un nuovo nome di tag nel webhook per memorizzare i valori aggiornati. Questo si applica ai webhook Jira, Jira Service Desk, Mattermost, Opsgenie, OTRS, Redmine, ServiceNow, Slack, Zammad e Zendesk forniti da Zabbix e alla maggior parte dei webhook che utilizzano l'opzione Include event menu entry. Tuttavia, un singolo webhook può essere usato in più operazioni o fasi di escalation della stessa azione, così come in azioni diverse che non verranno attivate dallo stesso evento di problema a causa di diverse condizioni.
  • Quando usi un webhook nelle azioni per eventi interni, assicurati di selezionare la casella Custom message e di definire un messaggio personalizzato nella configurazione dell'operazione dell'azione. In caso contrario, non verrà inviata alcuna notifica.