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

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 di Pocket Alert sul telefono e un account. Registrati se non ce l'hai; il piano gratuito basta per iniziare.
- Una chiave API da Chiavi API (percorso 1) oppure un webhook da 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:
| Percorso 1: API di Pocket Alert | Percorso 2: URL webhook di Pocket Alert | |
|---|---|---|
| URL di invio | https://api.pocketalert.app/v1/messages | https://p4a.me/wh/<slug> |
| Titolo della push | Il tuo, ad esempio Down: Website | Sempre Webhook <nome> |
| Down forte, Up silenzioso | Sì | Sì, con un body personalizzato; altrimenti un unico livello per tutto |
| Segreto conservato in Uptime Kuma | Una chiave API con pieno accesso al tuo account | Un URL che può solo creare push tramite quel webhook |
| Log delle richieste in Pocket Alert | No | Sì, nella cronologia webhook |
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:
{
"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) eheartbeatJSON(il controllo che ha cambiato stato).heartbeatJSON.statusè0per giù e1per su. | jsonscrive 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 chiamatoBob's "main" siteproduce comunque JSON valido.- Giù è
high, Su èlow.highè a priorità temporale su iPhone e supera Full immersion e il riepilogo programmato.lowviene consegnato senza interromperti. - Assegna il tag
criticala un monitor per renderlo più forte. Aggiungi un tag chiamatocriticalin Uptime Kuma ai monitor più importanti, e i loro guasti vengono inviati comecritical, che suona anche con l'interruttore silenzioso e con Non disturbare. Le notifiche critiche sono una funzione a pagamento; nel piano gratuito vengono consegnate comehigh. - 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 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:
{
"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" }
]
}
{
"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:
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: 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):
{
"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:
[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:
| Impostazione | Cosa fa | Consigliato |
|---|---|---|
| Retry | Controlli falliti marcati come In attesa prima che il monitor conti come giù. I controlli in attesa non notificano. | 2 o 3 |
| Intervallo di retry | Secondi tra un controllo e l'altro mentre è in attesa. | 20 - 60 |
| Rinvia la notifica se giù per X volte consecutive | Ripete l'avviso di giù dopo questo numero di controlli falliti aggiuntivi. 0 lo invia una sola volta. | 0, oppure un valore che corrisponde a 30-60 minuti |
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
Tokenmanca oppure la chiave è stata revocata. Creane una nuova da Chiavi API. - 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 per vedere esattamente cosa invia Uptime Kuma. - Un ripristino sembra mancare. Le push
lowsono 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 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 copre gli avvisi di backup e disco dallo stesso homelab.
Crea un account gratuito, incolla il body in una notifica Webhook e lascia che il prossimo guasto raggiunga il telefono mentre il ripristino attende in silenzio nel feed.