# Notifiche Uptime Kuma sul telefono: forti quando va giù, silenziose quando torna su

> Invia gli avvisi down e up di Uptime Kuma su iPhone e Android con la notifica Webhook integrata. I guasti arrivano con priorità alta, i ripristini arrivano in silenzio, la scadenza del certificato ha una notifica push dedicata e i retry evitano che un check instabile inondi il telefono.

*26.10.2026*

<!-- source: https://pocketalert.app/it/blog/uptime-kuma-notifications -->

Uptime Kuma è bravo a notare quando qualcosa è giù. Dove finisce quell'avviso è un altro discorso. La maggior parte delle configurazioni lo manda a un gruppo Telegram, a un canale Discord o a una cartella email, accanto a tutto il resto che fa vibrare il telefono durante la giornata. E il messaggio "tornato su" fa esattamente lo stesso rumore di quello "giù", così dopo qualche notte di falsi allarmi la gente silenzia il canale e smette di leggerlo.

Questa guida invia gli avvisi di Uptime Kuma a Pocket Alert come notifiche push con priorità diverse. Un monitor che va giù arriva come `high`, che passa la modalità Full immersion su iPhone. Un ripristino arriva come `low`: è nel feed quando lo guardi, e non sveglia nessuno. Tutto usa il tipo di notifica **Webhook** integrato in Uptime Kuma, quindi non c'è nulla da installare in più.

Tutto il contenuto qui sotto è stato testato su Uptime Kuma 2.5.8 in esecuzione su Docker.

## Di cosa hai bisogno

- Uptime Kuma 2.x. Gran parte di questo funziona anche con la 1.23.x; le differenze sono indicate alla fine.
- L'[app](/get-app) di Pocket Alert sul telefono e un account. [Registrati](/signup) se non ce l'hai; il piano gratuito basta per iniziare.
- Una chiave API da [Chiavi API](/account/apikeys) (percorso 1) oppure un webhook da [Webhooks](/webhooks) (percorso 2).

## Due modi per collegarli

La notifica Webhook di Uptime Kuma può inviare a qualsiasi URL, con il proprio JSON oppure con un body che scrivi tu. Ci sono quindi due percorsi:

<div class="cmp-table-wrap">
<table class="cmp-table">
<thead><tr><th></th><th>Percorso 1: API di Pocket Alert</th><th>Percorso 2: URL webhook di Pocket Alert</th></tr></thead>
<tbody>
<tr><th>URL di invio</th><td><code>https://api.pocketalert.app/v1/messages</code></td><td><code>https://p4a.me/wh/&lt;slug&gt;</code></td></tr>
<tr><th>Titolo della push</th><td>Il tuo, ad esempio <strong>Down: Website</strong></td><td>Sempre <strong>Webhook &lt;nome&gt;</strong></td></tr>
<tr><th>Down forte, Up silenzioso</th><td>Sì</td><td>Sì, con un body personalizzato; altrimenti un unico livello per tutto</td></tr>
<tr><th>Segreto conservato in Uptime Kuma</th><td>Una chiave API con pieno accesso al tuo account</td><td>Un URL che può solo creare push tramite quel webhook</td></tr>
<tr><th>Log delle richieste in Pocket Alert</th><td>No</td><td>Sì, nella <a href="/it/features/webhook-history">cronologia webhook</a></td></tr>
</tbody>
</table>
</div>

**Scegli il percorso 1** se vuoi titoli leggibili e il minor numero di parti in movimento. **Scegli il percorso 2** se preferisci non salvare una chiave API completa in Uptime Kuma (conserva le impostazioni delle notifiche, header inclusi, come JSON in chiaro nel suo database), oppure se vuoi che ogni richiesta inviata sia registrata dal lato Pocket Alert per il debug.

## Percorso 1: invio diretto all'API di Pocket Alert

In Uptime Kuma apri **Impostazioni → Notifiche** e clicca **Configura notifica**. Compila così:

- **Tipo di notifica:** Webhook
- **Nome descrittivo:** `Pocket Alert`
- **Post URL:** `https://api.pocketalert.app/v1/messages`
- **Metodo HTTP:** POST
- **Corpo della richiesta:** Corpo personalizzato

Incolla questo nel campo del body, sostituendo `kuma.example.com` con l'indirizzo del tuo Uptime Kuma:

```
{%- assign level = "default" -%}
{%- assign title = "Uptime Kuma" -%}
{%- assign text = msg -%}
{%- if heartbeatJSON -%}
  {%- assign text = heartbeatJSON.msg | default: msg -%}
  {%- if heartbeatJSON.status == 0 -%}
    {%- assign title = "Down: " | append: monitorJSON.name -%}
    {%- assign level = "high" -%}
    {%- for tag in monitorJSON.tags -%}
      {%- if tag.name == "critical" -%}{%- assign level = "critical" -%}{%- endif -%}
    {%- endfor -%}
  {%- else -%}
    {%- assign title = "Up: " | append: monitorJSON.name -%}
    {%- assign level = "low" -%}
  {%- endif -%}
{%- elsif msg contains "will expire" -%}
  {%- assign title = "Expiring soon" -%}
{%- endif -%}
{
  "title": {{ title | json }},
  "message": {{ text | json }},
  "level": "{{ level }}",
  "actions": [
    {
      "type": "view",
      "label": "Open in Uptime Kuma",
      "value": "https://kuma.example.com/dashboard/{{ monitorJSON.id }}"
    }
  ]
}
```

Poi attiva **Header aggiuntivi** e incolla:

```json
{
  "Token": "YOUR_API_KEY",
  "Content-Type": "application/json"
}
```

Cosa fa il body:

- **Il body è un template Liquid.** Uptime Kuma gli passa `msg` (il suo testo già pronto), `monitorJSON` (il monitor) e `heartbeatJSON` (il controllo che ha cambiato stato). `heartbeatJSON.status` è `0` per giù e `1` per su.
- **`| json` scrive una stringa JSON completa, virgolette incluse.** I messaggi d'errore e i nomi dei monitor possono contenere virgolette e backslash; con il filtro non possono rompere la richiesta. Un monitor chiamato `Bob's "main" site` produce comunque JSON valido.
- **Giù è `high`, Su è `low`.** `high` è a priorità temporale su iPhone e supera Full immersion e il riepilogo programmato. `low` viene consegnato senza interromperti.
- **Assegna il tag `critical` a un monitor per renderlo più forte.** Aggiungi un tag chiamato `critical` in Uptime Kuma ai monitor più importanti, e i loro guasti vengono inviati come `critical`, che suona anche con l'interruttore silenzioso e con Non disturbare. Le notifiche critiche sono una funzione a pagamento; nel piano gratuito vengono consegnate come `high`.
- **I messaggi di certificato e di test non hanno heartbeat.** Per questi, la push usa il testo di Uptime Kuma come messaggio. Lo stesso testo è il fallback quando il messaggio dell'heartbeat è vuoto, come capita a un monitor ping che torna su; l'API rifiuta una push con messaggio vuoto.
- **Il pulsante apre il monitor.** `/dashboard/<id>` è la pagina del monitor in Uptime Kuma. Per un avviso di certificato non c'è un ID monitor, e il pulsante apre invece la dashboard. I pulsanti di azione sono una funzione a pagamento; nel piano gratuito l'API li elimina e la push viene consegnata senza. Vedi [pulsanti di azione](/features/action-buttons) per le altre cose che possono fare.

**Non saltare l'header `Content-Type`.** Quando Uptime Kuma invia un body personalizzato, lo etichetta come `application/x-www-form-urlencoded` se non indichi diversamente. È quello che ha inviato nel mio test. L'API di Pocket Alert accetta solo JSON o multipart e risponde a quella richiesta con `400`.

Clicca **Test**. Una push intitolata "Uptime Kuma" con il testo "Pocket Alert Testing" dovrebbe arrivare entro pochi secondi. Salva.

Ecco cosa ha inviato Uptime Kuma 2.5.8 durante un vero guasto e un vero ripristino:

```json
{
  "title": "Down: Website",
  "message": "timeout of 4000ms exceeded",
  "level": "high",
  "actions": [
    { "type": "view", "label": "Open in Uptime Kuma", "value": "https://kuma.example.com/dashboard/1" }
  ]
}
```

```json
{
  "title": "Up: Website",
  "message": "200 - OK",
  "level": "low",
  "actions": [
    { "type": "view", "label": "Open in Uptime Kuma", "value": "https://kuma.example.com/dashboard/1" }
  ]
}
```

Usa una chiave API separata con il nome di Uptime Kuma, così puoi revocarla da sola se quel server dovesse mai essere compromesso.

## Percorso 2: un URL webhook di Pocket Alert

Qui Uptime Kuma invia il proprio JSON a un webhook di Pocket Alert, e un template dal lato Pocket Alert lo trasforma in una push.

### Crea il webhook

Il template dei pulsanti si può impostare solo tramite API, quindi il modo più rapido è una sola chiamata. Crea un webhook chiamato "Uptime Kuma" con un template del messaggio, un livello predefinito `high` (`1`) e un pulsante "Open in Uptime Kuma", poi stampa l'URL di ricezione:

```bash
PA_KEY='your-api-key'
KUMA_URL='https://kuma.example.com'

jq -n --arg kuma "$KUMA_URL" '{
  name: "Uptime Kuma",
  message: "%msg%",
  default_level: 1,
  actions: ([{type: "view", label: "Open in Uptime Kuma", value: ($kuma + "/dashboard/%monitor.id%")}] | tojson)
}' |
curl -sS https://api.pocketalert.app/v1/webhooks \
  -H "Token: $PA_KEY" \
  -H 'Content-Type: application/json' \
  --data-binary @- |
jq -r '"Receive URL: https://p4a.me/wh/" + .url'
```

Se preferisci usare il clic, crealo dalla console in [Webhooks](/webhooks): nome **Uptime Kuma**, **Priorità predefinita** Alta, messaggio `%msg%`. Ottieni le stesse push senza il pulsante.

### Collega Uptime Kuma

Configura una nuova notifica di tipo **Webhook**, incolla l'URL di ricezione come **Post URL** e imposta **Corpo della richiesta** su **Preset - application/json**. Non servono header: l'URL è il segreto, quindi trattalo come una password. Non scegliere il preset multipart; i webhook di Pocket Alert leggono solo JSON.

Uptime Kuma ha inviato questo dal mio setup di test quando un monitor è andato giù (accorciato; l'oggetto `monitor` ha circa cento campi):

```json
{
  "heartbeat": {
    "monitorID": 1,
    "status": 0,
    "time": "2026-10-31 16:09:56.331",
    "msg": "timeout of 4000ms exceeded",
    "important": true,
    "localDateTime": "2026-10-31 16:09:56"
  },
  "monitor": {
    "id": 1,
    "name": "Website",
    "url": "http://tls-target/",
    "type": "http",
    "tags": []
  },
  "msg": "[Website] [🔴 Down] timeout of 4000ms exceeded"
}
```

Il template `%msg%` usa il `msg` di primo livello, perché è l'unico campo presente in ogni richiesta. Per gli avvisi di certificato e i messaggi di test, `heartbeat` e `monitor` sono `null` e solo `msg` è valorizzato. La push arriva intitolata "Webhook Uptime Kuma" con "[Website] [🔴 Down] timeout of 4000ms exceeded" come testo. Un segnaposto il cui percorso manca viene reso come stringa vuota, quindi su un avviso di certificato il pulsante punta a `/dashboard/` e continua a funzionare.

### Giù forte, Su silenzioso su questo percorso

Con il preset JSON, ogni richiesta riceve il livello predefinito del webhook, quindi anche i ripristini arrivano forti come i guasti. Per correggerlo, imposta **Corpo della richiesta** su **Corpo personalizzato** e invia tu un campo `level`. I webhook di Pocket Alert leggono un `level` di primo livello dal payload prima di ricorrere al valore predefinito:

```
{
  "level": "{% if heartbeatJSON %}{% if heartbeatJSON.status == 0 %}high{% else %}low{% endif %}{% else %}default{% endif %}",
  "msg": {{ msg | json }},
  "monitor": { "id": "{{ monitorJSON.id }}" }
}
```

Il body mantiene i nomi dei campi `msg` e `monitor.id`, quindi i template del messaggio e del pulsante del webhook funzionano senza modifiche. I webhook di Pocket Alert leggono il body come JSON qualunque sia il suo `Content-Type`, quindi questo percorso non richiede header aggiuntivi.

## Attivalo per ogni monitor

Una notifica non fa nulla finché un monitor non la usa. In fondo al modulo della notifica ci sono due interruttori:

- **Attiva di default** abilita questa notifica su ogni monitor che crei da ora in poi.
- **Applica a tutti i monitor esistenti** la aggiunge a tutti i monitor che hai già. Viene eseguito una volta al salvataggio e non viene ricordato.

Attivali entrambi al primo salvataggio. Per escludere un monitor, aprilo e deseleziona la notifica nel suo modulo di modifica.

## Avvisi di scadenza del certificato

Uptime Kuma può avvisarti prima che un certificato TLS scada. Apri un monitor HTTP(s) (anche i monitor Keyword e JSON Query lo hanno) e spunta **Notifica scadenza certificato** in **Avanzate**. La casella è disattivata mentre **Ignora gli errori TLS/SSL per i siti HTTPS** è attiva.

Le soglie sono globali, in **Impostazioni → Notifiche → Scadenza certificato TLS**, e di default sono 7, 14 e 21 giorni. L'avviso va alle stesse notifiche dei guasti del monitor, con un testo come:

```text
[TLS site][https://tls-target/] server certificate tls-target will expire in 4 days
```

Il body del percorso 1 lo intercetta con `msg contains "will expire"` e lo intitola "Expiring soon" con livello `default`. Uptime Kuma lo invia una volta per soglia, non a ogni controllo: nel mio test il monitor è stato controllato 119 volte con un certificato a quattro giorni dalla scadenza, e è partito esattamente un avviso.

## Evita che un monitor instabile inondi il telefono

Tre impostazioni del monitor decidono quanto rumore fa un servizio instabile:

<div class="cmp-table-wrap">
<table class="cmp-table">
<thead><tr><th>Impostazione</th><th>Cosa fa</th><th>Consigliato</th></tr></thead>
<tbody>
<tr><th>Retry</th><td>Controlli falliti marcati come <strong>In attesa</strong> prima che il monitor conti come giù. I controlli in attesa non notificano.</td><td><code>2</code> o <code>3</code></td></tr>
<tr><th>Intervallo di retry</th><td>Secondi tra un controllo e l'altro mentre è in attesa.</td><td><code>20</code> - <code>60</code></td></tr>
<tr><th>Rinvia la notifica se giù per X volte consecutive</th><td>Ripete l'avviso di giù dopo questo numero di controlli falliti aggiuntivi. <code>0</code> lo invia una sola volta.</td><td><code>0</code>, oppure un valore che corrisponde a 30-60 minuti</td></tr>
</tbody>
</table>
</div>

Con **Retry** impostato a 2 nel mio test, i primi due controlli falliti sono stati marcati come in attesa e solo il terzo ha inviato "Down". Con **Rinvio** impostato a 3, l'avviso di giù si è ripetuto dopo ogni tre controlli falliti aggiuntivi finché il servizio non è tornato su. Il conteggio dei rinvii è in controlli, non in minuti. Con un intervallo di 60 secondi, 30 significa un promemoria ogni mezz'ora.

Ogni avviso di giù, ogni ritorno su e ogni rinvio è un messaggio. Il piano gratuito ne consente 50 al giorno, quindi un solo monitor instabile senza retry può esaurirli in un pomeriggio. I retry sono la correzione più economica.

## Se non arriva nulla

- **Il test fallisce con HTTP 400.** Nel percorso 1, verifica che **Header aggiuntivi** includa `"Content-Type": "application/json"`. Senza, la richiesta parte come dati di form.
- **HTTP 401.** L'header `Token` manca oppure la chiave è stata revocata. Creane una nuova da [Chiavi API](/account/apikeys).
- **Il test arriva ma i guasti no.** Apri il monitor e controlla che la notifica sia selezionata. Inoltre, Uptime Kuma non notifica al primo controllo di un monitor se è su, quindi un monitor nuovo resta silenzioso finché qualcosa non cambia.
- **Il percorso 2 non mostra nulla.** Apri la cronologia del webhook nella console. Se la richiesta c'è con un errore, indica il motivo: JSON non valido, oppure un template che ha prodotto un messaggio vuoto. Se non c'è nessuna registrazione, Uptime Kuma non ha mai raggiunto `p4a.me`. Puoi anche inviare richieste al [tester webhook](/tools/webhook) per vedere esattamente cosa invia Uptime Kuma.
- **Un ripristino sembra mancare.** Le push `low` sono silenziose. Controlla il feed nell'app.

## FAQ

### Quale versione di Uptime Kuma serve?

È stato testato sulla 2.5.8, l'ultima release al momento della scrittura. La versione 1.23.x ha anch'essa il tipo Webhook con Corpo personalizzato e Header aggiuntivi, e il suo template riceve le stesse variabili `msg`, `monitorJSON` e `heartbeatJSON`. Ho generato il body del percorso 1 con il motore di template incluso nella 1.23.16 e ho ottenuto lo stesso JSON, ma l'esecuzione end-to-end completa è stata fatta solo sulla 2.5.8.

### Cosa succede se il server che esegue Uptime Kuma va giù?

Allora nessuno invia l'avviso. Uptime Kuma non può segnalare il proprio guasto, quindi usa qualcosa esterno che se ne accorga, come un controllo da un'altra macchina o un monitor ospitato. La pagina [monitoraggio uptime](/use-cases/uptime-monitoring) elenca i monitor ospitati che funzionano con i webhook di Pocket Alert.

### Posso inviare monitor diversi a telefoni diversi?

Sì, con un piano a pagamento. Crea una notifica per gruppo con un `device_id` diverso nel body (percorso 1) oppure un webhook diverso con il proprio dispositivo (percorso 2), e seleziona quella giusta su ogni monitor. Il piano gratuito ha un dispositivo e un webhook, quindi c'è un solo telefono a cui inviare.

### Funziona per i monitor ping, porta e DNS?

Sì. Il body usa solo il nome e l'ID del monitor e lo stato e il messaggio dell'heartbeat, che ogni tipo di monitor ha. Alcuni tipi, tra cui il ping, lasciano il messaggio vuoto quando il controllo riesce; il body allora ricorre al testo di Uptime Kuma. Il pulsante rimanda alla pagina del monitor in Uptime Kuma e non all'indirizzo controllato, quindi funziona anche quando l'indirizzo non è un URL.

### Lo uso già per Proxmox. Posso condividere la chiave API?

Puoi, ma dai a Uptime Kuma una chiave sua, così revocarne una non rompe l'altra. La [guida Proxmox](/blog/proxmox-alerts) copre gli avvisi di backup e disco dallo stesso homelab.

[Crea un account gratuito](/signup), incolla il body in una notifica Webhook e lascia che il prossimo guasto raggiunga il telefono mentre il ripristino attende in silenzio nel feed.
