Impostazioni webhook
Scopri come configurare i template dei messaggi webhook per estrarre dati dai payload JSON in arrivo.
Sintassi del template dei messaggi
Quando crei un webhook, definisci un template dei messaggi che stabilisce come i dati JSON in arrivo vengono formattati nelle notifiche.
Pattern di base
| Pattern | Descrizione |
|---|---|
* | Restituisce l'intero payload JSON |
%field% | Estrae un campo di primo livello |
%object.field% | Estrae un campo annidato |
%array.0% | Ottiene il primo elemento di un array |
%array.0.field% | Ottiene un campo da un elemento dell'array |
%% | Un % letterale. Serve solo subito prima di una parola seguita da un altro %, come in %cpu%%%; un % seguito da uno spazio, come in 90% on %host%, resta invariato |
Un placeholder non contiene mai spazi, quindi i simboli di percentuale nel testo normale non vengono modificati: CPU over 90% on %host% viene visualizzato come CPU over 90% on db-1.
Esempi
Payload JSON di esempio
Considera questo payload webhook in arrivo:
{
"event": {
"title": "New Order",
"message": "A new order has been placed with ID 12345",
"tags": ["order", "new"],
"users": [
{"first": "Dale", "last": "Murphy", "age": 44, "nets": ["ig", "fb", "tw"]},
{"first": "Roger", "last": "Craig", "age": 68, "nets": ["fb", "tw"]},
{"first": "Jane", "last": "Murphy", "age": 47, "nets": ["ig", "tw"]}
]
}
}Configurazione del template
*Title: %event.title%
Message: %event.message%
Tags: %event.tags%
Users: %event.users.0%
First user: %event.users.0.first% %event.users.0.last%Risultato dell'output
Title: New Order
Message: A new order has been placed with ID 12345
Tags: ["order","new"]
Users: {"age":44,"first":"Dale","last":"Murphy","nets":["ig","fb","tw"]}
First user: Dale MurphyIntegrazioni comuni
Webhook di GitHub
🔔 %action%: %repository.full_name%
%sender.login%: %commits.0.message%Monitoraggio errori con Sentry
Per un'integrazione interna usata come azione di avviso (issue alerts):
🚨 %data.event.title%
%data.event.culprit%
Rule: %data.triggered_rule%Aggiungi un pulsante view con %data.event.web_url% per aprire l'issue. Il plugin Webhooks legacy invia un payload diverso: in quel caso usa %project_name%: %event.title% e %url%.
Avvisi di Grafana
⚠️ %state%: %title%
%message%
Status: %status%Uptime Robot
🔴 %monitorFriendlyName%
Status: %alertTypeFriendlyName%
Details: %alertDetails%Sintassi avanzata dei percorsi
Per l'estrazione di JSON più complessa, usiamo la sintassi dei percorsi GJSON.
Pattern utili
| Pattern | Descrizione |
|---|---|
%users.#% | Numero di elementi dell'array |
%users.#.first% | Array di tutti i valori first |
%users.@reverse% | Inverte l'ordine dell'array |
%data.@pretty% | Stampa il JSON formattato |
Scopri di più
Documentazione completa: sintassi dei percorsi GJSON
Livello di priorità
I payload in arrivo possono contenere un campo level per controllare come viene consegnata la notifica push: un nome (silent, low, default, high, critical) oppure un intero (-2..2). Vedi Livelli di priorità dei messaggi.
Ordine di risoluzione (vince la prima corrispondenza):
- Il campo
levelnel payload JSON in arrivo - Il
default_leveldel webhook (impostato durante la creazione del webhook) - Il livello predefinito dell'applicazione
default(normale)
A differenza dell'API diretta, l'input dei webhook è tollerante: un valore level non riconosciuto viene ignorato (ripiegando sui valori predefiniti) anziché rifiutato, così gli avvisi non vengono mai scartati.
Pulsanti di azione
Un webhook può allegare fino a 3 pulsanti di azione a ogni notifica che genera. Imposta il campo actions (una stringa JSON) quando crei o aggiorni il webhook — vedi Crea webhook → Template dei pulsanti di azione.
label e value supportano gli stessi placeholder %field.path% del template dei messaggi, quindi i pulsanti possono essere costruiti a partire dal payload in arrivo:
[
{ "type": "view", "label": "Open PR", "value": "%pull_request.html_url%" },
{ "type": "http", "label": "Merge", "value": "{\"url\":\"https://ci.example.com/merge/%pull_request.number%\",\"method\":\"POST\"}" }
]Dopo la sostituzione, ogni pulsante viene validato (type ∈ view/http/copy; view e http richiedono un URL http(s)). Come per il parsing del livello, il controllo è tollerante: un pulsante non valido viene scartato da solo, mentre gli altri pulsanti e la notifica vengono comunque consegnati.
I pulsanti di azione sono una funzionalità a pagamento. Nei piani gratuiti vengono rimossi e la notifica viene consegnata senza di essi.
Dopo aver creato un webhook, puoi testarlo:
curl -X POST "https://p4a.me/wh/YOUR_WEBHOOK_URL" \
-H "Content-Type: application/json" \
-d '{"event": {"title": "Test", "message": "Hello World"}}'await fetch('https://p4a.me/wh/YOUR_WEBHOOK_URL', {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify({
event: { title: 'Test', message: 'Hello World' }
})
});import requests
requests.post(
'https://p4a.me/wh/YOUR_WEBHOOK_URL',
json={'event': {'title': 'Test', 'message': 'Hello World'}}
)Http::post('https://p4a.me/wh/YOUR_WEBHOOK_URL', [
'event' => [
'title' => 'Test',
'message' => 'Hello World',
],
]);Questo invierà una notifica di test ai tuoi dispositivi usando il template dei messaggi configurato.