4 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

Sono disponibili le seguenti integrazioni, che consentono di utilizzare tipi di supporto webhook predefiniti per inviare notifiche di Zabbix a:

Oltre ai servizi elencati qui, Zabbix può essere integrato con Spiceworks (non è richiesto alcun webhook). Per convertire le notifiche di Zabbix in ticket di Spiceworks, creare un tipo di supporto email e inserire l'indirizzo email dell'helpdesk di Spiceworks (ad esempio, help\@zabbix.on.spiceworks.com) 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 nella propria installazione di Zabbix. Il webhook apparirà nell'elenco dei tipi di supporto.
  3. Configurare il webhook secondo le istruzioni nel file Readme.md (è possibile fare clic sul nome di un webhook sopra per accedere rapidamente a Readme.md).

Per creare un webhook personalizzato da zero:

  1. Andare in Avvisi > Tipi di supporto.
  2. Fare clic su Crea tipo di supporto.

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-valore.
Per i webhook preconfigurati, l'elenco dei parametri varia a seconda del servizio. Consultare il file Readme.md del webhook per la descrizione dei parametri.
Per i nuovi webhook, per impostazione predefinita sono incluse diverse variabili comuni (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 la stessa funzionalità del campo proxy HTTP nella configurazione dell'item. La stringa del proxy può essere preceduta da [scheme]:// per specificare quale tipo di proxy viene 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 della matita accanto ad esso. Questo codice eseguirà l'operazione del webhook.
Lo script è il codice di 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 controllare le intestazioni HTTP e il corpo della richiesta.
Lo script deve contenere un operatore return, altrimenti non sarà valido. Può restituire uno 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 (sia generati automaticamente sia come risultato di una chiusura manuale) vengono creati dal server e includono i tag dell'evento risolto (compresi i tag 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 es. var local = 1) invece di variabili globali (ad es. 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 di webhook, Esempi di script webhook, Oggetti JavaScript aggiuntivi.
Timeout Timeout di esecuzione di JavaScript (1-60s, predefinito 30s).
I suffissi temporali sono supportati, ad es. 30s, 1m.
Elabora tag Selezionare la casella per elaborare i valori delle proprietà JSON restituite come tag. Questi tag vengono aggiunti a eventuali tag di problema esistenti.
Si noti che 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 evento Selezionare la casella per includere una voce nel menu evento che rimandi a un ticket esterno creato.
Verrà inclusa una voce per ogni webhook abilitato che ha questa casella selezionata. Si noti che se i parametri Nome voce di menu e URL voce di menu contengono macro {EVENT.TAGS.<tag name>}, una voce verrà inclusa solo se tali macro possono essere risolte (ossia se l'evento ha questi tag definiti).
Se selezionata, il webhook non deve essere utilizzato per inviare notifiche a utenti diversi (valutare invece la creazione di un utente dedicato) e non deve essere utilizzato in più azioni di avviso per un singolo evento di problema.
Nome voce di menu Specificare il nome della voce di menu.
La macro {EVENT.TAGS.<tag name>} è supportata.
Questo campo è obbligatorio solo se Includi voce nel menu evento è selezionato.
URL voce di menu Specificare l'URL sottostante della voce di menu.
La macro {EVENT.TAGS.<tag name>} è supportata.
Questo campo è obbligatorio solo se Includi voce nel menu evento è selezionato.

Per i dettagli su come configurare i messaggi predefiniti e le opzioni di elaborazione degli avvisi, vedere i parametri comuni del tipo di supporto.

Anche se un webhook non utilizza i messaggi predefiniti, i template di messaggio per i tipi di operazione utilizzati da questo webhook devono comunque essere definiti.

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 non riuscirà.
  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 log di test del tipo di supporto senza uscire dalla finestra di test, fare clic su Open log (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 utente

Una volta configurato il tipo di supporto, vai alla sezione Utenti > Utenti e assegna il supporto webhook a un utente esistente oppure crea un nuovo utente che rappresenti il webhook. I passaggi per configurare i supporti utente per un utente esistente, comuni a tutti i tipi di supporto, sono descritti nella pagina Tipi di supporto.

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

  1. Dopo aver configurato il tipo di supporto webhook, vai alla sezione Utenti > Utenti e crea un utente Zabbix dedicato che rappresenti il webhook, ad esempio con il nome utente Slack per il webhook Slack. Tutte le impostazioni, tranne i supporti, possono essere lasciate ai valori predefiniti, poiché questo utente non accederà a Zabbix.
  2. Nel profilo utente, vai alla scheda Media e aggiungi un webhook con le informazioni di contatto richieste. Se il webhook non utilizza un campo Send to, inserisci una qualsiasi combinazione di caratteri supportati per aggirare i requisiti di convalida.
  3. Concedi a questo utente almeno i permessi di lettura a tutti gli host per i quali deve inviare gli avvisi.

Quando configuri un'azione di avviso, aggiungi questo utente nel campo Send to users nei dettagli dell'operazione: questo indicherà a Zabbix di utilizzare il webhook per le notifiche di questa azione.

Configurazione delle azioni di avviso

Le azioni determinano quali notifiche devono essere inviate tramite il webhook. I passaggi per la configurazione delle azioni che coinvolgono i webhook sono gli stessi di tutti gli altri tipi di supporto, con le seguenti eccezioni:

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