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 le 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 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.

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 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 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 controllare 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.

Tenere presente che lo script viene eseguito solo dopo la creazione di un avviso. Se lo script è configurato per restituire ed elaborare i tag, questi tag non verranno risolti nelle macro {EVENT.TAGS} e {EVENT.RECOVERY.TAGS} del messaggio iniziale del problema e dei messaggi di ripristino, perché lo script non ha ancora avuto il tempo di essere eseguito.
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 collisioni 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 a tutti i tag esistenti del problema.
Tenere presente 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 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 e con questa casella selezionata. Tenere presente 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 queste 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 invece 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 Includi voce nel menu degli eventi è 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 degli eventi è selezionato.

Vedere parametri comuni dei tipi di supporto per informazioni dettagliate sulla configurazione dei messaggi predefiniti e delle opzioni di elaborazione degli avvisi.

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 media webhook configurato:

  1. Individua il webhook pertinente nell'elenco dei tipi di media.
  2. Fai clic su Test nell'ultima colonna dell'elenco (si aprirà una finestra di test).
  3. Modifica i valori dei parametri del webhook secondo necessità. Sostituisci le macro con valori di esempio; in caso contrario, le macro non verranno risolte e il test fallirà.
  4. Fai 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 media senza uscire dalla finestra di test, fai 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.