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

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 help\@zabbix.on.spiceworks.com) nelle impostazioni del profilo di un utente Zabbix designato.

Configurazione

Per iniziare a usare un'integrazione webhook:

  1. Individua il file .yaml richiesto nella directory templates/media della versione di Zabbix scaricata oppure scaricalo dal repository git di Zabbix.
  2. Importa il file nella tua installazione di Zabbix. Il webhook apparirà nell'elenco dei tipi di media.
  3. Configura il webhook seguendo le istruzioni nel file Readme.md (puoi fare clic sul nome di un webhook sopra per accedere rapidamente a Readme.md).

Per creare un webhook personalizzato da zero:

  1. Vai su Alerts > Media types.
  2. Fai clic su Create media type.

La scheda Media type contiene vari attributi specifici per questo tipo di media:

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

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

Parameter Description
Parameters Specifica le variabili del webhook come coppie attributo-valore.
Per i webhook preconfigurati, l'elenco dei parametri varia a seconda del servizio. Consulta il file Readme.md del webhook per la descrizione dei parametri.
Per i nuovi webhook, alcune variabili comuni sono incluse per impostazione predefinita (URL:<empty>, HTTPProxy:<empty>, To:{ALERT.SENDTO}, Subject:{ALERT.SUBJECT}, Message:{ALERT.MESSAGE}); puoi lasciarle oppure rimuoverle.

I parametri del webhook supportano user macros, tutte le macros supportate nelle notifiche di problema e, inoltre, le macro {ALERT.SENDTO}, {ALERT.SUBJECT} e {ALERT.MESSAGE}.

Se specifichi un proxy HTTP, il campo supporta la stessa funzionalità del campo HTTP proxy nella configurazione dell'item. La stringa del proxy può essere preceduta da [scheme]:// per specificare quale tipo di proxy viene usato (ad esempio, https, socks4, socks5; vedi documentazione).
Script Inserisci il codice JavaScript nell'editor modale che si apre facendo clic nel campo del parametro o sull'icona a forma di matita accanto ad esso. Questo codice eseguirà l'operazione del webhook.
Il codice è una funzione che accetta coppie parametro-valore. I valori devono essere convertiti in oggetti JSON usando 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 ha il controllo sulle intestazioni HTTP e sul corpo della richiesta.
Lo script deve contenere un operatore return, altrimenti non sarà valido. Può restituire uno stato OK insieme a un elenco opzionale di tag e valori dei tag (vedi l'opzione Process tags) oppure una stringa di errore.

Nota che lo script viene eseguito solo dopo la creazione di un alert. Se lo script è configurato per restituire ed elaborare i tag, questi tag non verranno risolti nelle macro {EVENT.TAGS} e {EVENT.RECOVERY.TAGS} nel messaggio iniziale del problema e nei messaggi di ripristino, perché lo script non ha ancora avuto il tempo di essere eseguito.
Nota: si consiglia di usare variabili locali (ad esempio var local = 1) invece di una globale (ad esempio global = 1) per garantire che ogni script operi sui propri dati ed evitare collisioni tra chiamate simultanee (vedi known issues).

Vedi anche: Webhook development guidelines, Webhook script examples, Additional JavaScript objects.
Timeout Timeout di esecuzione di JavaScript (1-60s, predefinito 30s).
Sono supportati i suffissi di tempo, ad esempio 30s, 1m.
Process tags Seleziona la casella per elaborare i valori delle proprietà JSON restituiti come tag. Questi tag vengono aggiunti a eventuali tag di problema già esistenti.
Nota che quando si usano webhook tags, 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>
Include event menu entry Seleziona la casella per includere una voce nel menu eventi che rimandi a un ticket esterno creato.
Verrà inclusa una voce per ogni webhook abilitato e con questa casella selezionata. Nota che se i parametri Menu entry name e Menu entry URL contengono macro {EVENT.TAGS.<tag name>}, una voce verrà inclusa solo se queste macro possono essere risolte (cioè se l'evento ha questi tag definiti).
Se selezionato, il webhook non dovrebbe essere usato per inviare notifiche a utenti diversi (valuta invece la creazione di un utente dedicato) e non dovrebbe essere usato in più azioni di alert per un singolo evento di problema.
Menu entry name Specifica il nome della voce di menu.
È supportata la macro {EVENT.TAGS.<tag name>}.
Questo campo è obbligatorio solo se Include event menu entry è selezionato.
Menu entry URL Specifica l'URL sottostante della voce di menu.
È supportata la macro {EVENT.TAGS.<tag name>}.
Questo campo è obbligatorio solo se Include event menu entry è selezionato.

Consulta i parametri comuni dei tipi di media per i dettagli su come configurare i messaggi predefiniti e le opzioni di elaborazione degli alert.

Anche se un webhook non usa i messaggi predefiniti, i modelli di messaggio per i tipi di operazione usati 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.