# 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:

```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

**Full JSON**

```text
*
```

**Extracted Fields**

```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](https://github.com/tidwall/gjson/blob/master/SYNTAX.md).

### 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 |

> **Tip: Scopri di più**
>
> Documentazione completa: [sintassi dei percorsi GJSON](https://github.com/tidwall/gjson/blob/master/SYNTAX.md)

## 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](https://info.pocketalert.app/api/messages/create.md#priority-levels).

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](https://info.pocketalert.app/api/webhooks/create.md#action-buttons-template).

`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:

**cURL**

```bash
curl -X POST "https://p4a.me/wh/YOUR_WEBHOOK_URL" \
  -H "Content-Type: application/json" \
  -d '{"event": {"title": "Test", "message": "Hello World"}}'
```

**JavaScript**

```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**

```python
import requests

requests.post(
    'https://p4a.me/wh/YOUR_WEBHOOK_URL',
    json={'event': {'title': 'Test', 'message': 'Hello World'}}
)
```

**PHP**

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