Vai al contenuto

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 ​

PatternDescrizione
*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:

json
{
  "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 ​

text
*
text
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 Murphy

Integrazioni comuni ​

Webhook di GitHub ​

text
🔔 %action%: %repository.full_name%
%sender.login%: %commits.0.message%

Monitoraggio errori con Sentry ​

Per un'integrazione interna usata come azione di avviso (issue alerts):

text
🚨 %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 ​

text
⚠️ %state%: %title%

%message%

Status: %status%

Uptime Robot ​

text
🔴 %monitorFriendlyName%
Status: %alertTypeFriendlyName%
Details: %alertDetails%

Sintassi avanzata dei percorsi ​

Per l'estrazione di JSON più complessa, usiamo la sintassi dei percorsi GJSON.

Pattern utili ​

PatternDescrizione
%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):

  1. Il campo level nel payload JSON in arrivo
  2. Il default_level del webhook (impostato durante la creazione del webhook)
  3. Il livello predefinito dell'applicazione
  4. 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:

json
[
  { "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:

bash
curl -X POST "https://p4a.me/wh/YOUR_WEBHOOK_URL" \
  -H "Content-Type: application/json" \
  -d '{"event": {"title": "Test", "message": "Hello World"}}'
javascript
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' }
  })
});
python
import requests

requests.post(
    'https://p4a.me/wh/YOUR_WEBHOOK_URL',
    json={'event': {'title': 'Test', 'message': 'Hello World'}}
)
php
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.

Documentazione di Pocket Alert