Notifiche push affidabili su iPhone da uno stack self-hosted

Il tuo alert Grafana scatta alle 3 di notte. I log del server dicono che la chiamata webhook è andata a buon fine. Il tuo iPhone resta muto. Il monitoraggio self-hosted è bravo a rilevare i guasti. Far arrivare il messaggio sul telefono è il punto in cui la maggior parte dei setup da homelab si rompe.
Questa guida spiega perché le notifiche push su iPhone da uno stack self-hosted sono difficili, come è fatto un percorso affidabile e come collegare Grafana, Uptime Kuma, n8n, cron job e script shell. Il primo alert funzionante richiede circa cinque minuti.
Perché le notifiche push su iOS si rompono nei setup self-hosted
Solo APNs può raggiungere un iPhone
Ogni notifica push verso un iPhone passa per Apple Push Notification service (APNs). Il tuo server non può aprire una connessione diretta con il telefono e inviargli dati. Il telefono mantiene una connessione persistente con Apple. Il tuo server invia ogni messaggio ad APNs tramite HTTP/2, autenticato con una chiave del tuo account sviluppatore Apple. APNs consegna poi il messaggio sulla connessione già aperta del telefono.
Questo significa che il tuo stack ha bisogno di un mittente in grado di parlare con APNs. Il telefono non interroga mai il tuo server, quindi un semplice endpoint webhook sulla tua LAN non ha nulla da consegnare. Per capire meglio il percorso di consegna, vedi come le notifiche push arrivano su iPhone.
Gestire un mittente proprio richiede più lavoro di quanto sembri
Puoi parlare con APNs direttamente. Ti servono una chiave di firma (un file .p8 per l'autenticazione con token, che non scade ogni anno, oppure un certificato client TLS per app, che invece scade), un'app registrata, un modo per salvare i token dei dispositivi e del codice che gestisca errori e tentativi di APNs. Ti serve anche un'app iOS che registri il dispositivo e mostri l'alert. Ogni pezzo è gestibile da solo. Il vero costo è mantenerli tutti funzionanti tra rotazioni delle chiavi e cambi delle policy Apple.
La maggior parte di chi self-hosta ha bisogno del risultato, non dell'infrastruttura. Un servizio hosted che gestisce già il lato APNs permette di tenere lo stack semplice: una richiesta HTTP per alert.
Focus, silenziamento e livelli di interruzione
iOS decide quanto forte consegnare ogni notifica in base al suo livello di interruzione, alle tue modalità Full immersion e alle impostazioni dell'app. Per gli alert contano tre cose:
- Le notifiche devono essere consentite per l'app. Controllalo per primo nelle Impostazioni di iOS. Un'app silenziata non mostrerà mai il tuo alert, qualunque cosa faccia il server.
- Le notifiche urgenti possono superare Full immersion. In Pocket Alert, i messaggi
higharrivano come urgenti. I livelli più bassi aspettano la fine della Full immersion. - Gli avvisi critici ignorano l'interruttore silenzioso e Non disturbare. Richiedono un'autorizzazione speciale che Apple concede dopo una revisione. Pocket Alert la possiede: i messaggi
criticalsui piani a pagamento riproducono un suono anche con il telefono silenziato, purché tu abbia consentito gli Avvisi critici per l'app. Se hai disattivato quel permesso, arrivano come urgenti.
La sezione sulle priorità qui sotto spiega come impostare il livello.
Come è fatto un setup affidabile
Il tuo stack rileva un problema e invia una richiesta HTTP. Da lì in poi se ne occupa un servizio hosted:
Grafana / Uptime Kuma / n8n / cron + CLI
│ HTTPS (API call or webhook)
▼
Pocket Alert ──► APNs ──► iPhone (Pocket Alert app)
La suddivisione del lavoro è questa:
| Il tuo stack fa | Pocket Alert fa |
|---|---|
| Rileva il guasto e decide cosa conta | Riceve la richiesta e verifica la tua chiave API o l'URL del webhook |
| Formatta il testo, oppure invia il proprio JSON | Mappa i campi, imposta il livello di priorità e consegna ad APNs |
| Invia l'evento una volta, quando accade | Invia a tutti i dispositivi dell'account, oppure al dispositivo che indichi |
| Tiene i propri log | Conserva la cronologia dei messaggi e un log delle richieste per ogni webhook, così puoi vedere cosa è arrivato e cosa è fallito |
Invia il primo alert con curl
Registrati su pocketalert.app/signup, apri chiavi API e clicca Create New Key. La chiave viene mostrata una sola volta, quindi copiala in un posto sicuro.
Salvala in una variabile d'ambiente e invia un messaggio:
export PA_KEY="YOUR_API_KEY"
curl -X POST "https://api.pocketalert.app/v1/messages" \
-H "Token: $PA_KEY" \
-H "Content-Type: application/json" \
-d '{
"title": "Backup finished",
"message": "nightly-backup on nas01 completed in 14m",
"level": "high"
}'
Una chiamata riuscita restituisce JSON con tid, title, message, application, device e created_at. Conserva il tid se vuoi associare in seguito una push a una riga di log.
Tre cose creano problemi:
- Imposta il Content-Type. L'API accetta JSON o
multipart/form-data. Rifiutaapplication/x-www-form-urlencoded, che è ciò che inviacurl -dse non imposti l'header. Usa-H "Content-Type: application/json"con un corpo JSON, oppure-Fper i campi di un form. titleemessagesono obbligatori. Tutto il resto è facoltativo.- Ometti
device_idper raggiungere tutti i dispositivi dell'account. Aggiungilo quando hai più telefoni e ne vuoi uno specifico.
Invia alert dalla riga di comando
La CLI di Pocket Alert è il modo più rapido per collegare gli alert agli script esistenti. Installala con lo script shell, Homebrew o Go:
curl -fsSL https://raw.githubusercontent.com/PocketAlert/cli/main/install.sh | sh
# or
brew install pocketalert/tap/pocketalert
# or
go install github.com/PocketAlert/cli/cmd/pocketalert@latest
Esegui una volta pocketalert auth e incolla la tua chiave. La chiave viene salvata in ~/.pocketalert/config.json, leggibile solo da te. Su server, container e CI, imposta invece POCKETALERT_API_KEY.
Invia un messaggio:
pocketalert send "Deploy finished" "v2.4.0 is live" --level high
Invia direttamente l'output di un comando in un alert:
df -h | pocketalert send "Disk report" --level default
Oppure avvolgi un comando con exec. Esegue il comando come al solito, poi invia una sola push con lo stato di uscita, la durata e le ultime righe di output, e restituisce lo stesso codice di uscita:
pocketalert exec -t "Database dump" -- ./dump.sh
Usa -q per stampare solo l'ID del messaggio, utile per gli script. Aggiungi --json a qualsiasi comando per un output leggibile dalle macchine.
Webhook con mappatura dei campi
Quando la tua sorgente invia già JSON, come Grafana, Uptime Kuma o un servizio personalizzato, non devi scrivere un mittente. Crea un webhook nella console su Webhook: Pocket Alert ti fornisce un URL di ricezione come https://p4a.me/wh/1234abcd. Lo slug non è indovinabile, e ogni URL è legato a un solo webhook e a una sola applicazione. Punta la tua sorgente a quell'URL con POST.
La push arriva con il titolo "Webhook" seguito dal nome del webhook, quindi dagli il nome della sorgente, per esempio Grafana. Il template del messaggio estrae i valori dal JSON in arrivo con i percorsi GJSON:
%object.field%per i campi annidati%items.0.name%per gli elementi di un array%users.#%per un conteggio*come template intero invia l'intero corpo
Per esempio, un template per un payload in arrivo come questo:
{
"service": "api-gateway",
"check": "tls-expiry",
"state": "warning",
"detail": "certificate expires in 6 days"
}
potrebbe essere:
[%state%] %service%: %check%
%detail%
Un segnaposto il cui percorso manca viene reso come stringa vuota, quindi un errore di battitura compare come un buco nel testo, non come un errore.
Prima di scrivere un template, acquisisci il payload reale. Apri il tester dei webhook, copia l'URL di test e punta la tua sorgente lì. Il tester mostra metodo, header e corpo, così puoi scrivere i percorsi in base a ciò che la tua sorgente invia davvero. Non inviare segreti di produzione a un URL di test pubblico. Chiunque conosca l'URL può leggere ciò che arriva lì.
La priorità funziona in due modi. Imposta un livello predefinito sul webhook, oppure includi nel payload un campo level di primo livello, che sovrascrive il predefinito. I valori validi sono silent, low, default, high e critical, oppure i numeri da -2 a 2. Un level non valido viene ignorato e si applica il predefinito del webhook.
Integrazioni
Alert Grafana
Nella console, crea un webhook chiamato Grafana con questo template del messaggio:
[%status%] %commonLabels.alertname% (%commonLabels.severity%)
%alerts.0.annotations.summary%
Copia il suo URL di ricezione. In Grafana, vai su Alerting → Contact points → Add contact point, scegli l'integrazione Webhook e imposta:
Integration: Webhook
URL: https://p4a.me/wh/1234abcd
Method: POST
Collega il contact point a una notification policy in modo che gli alert corrispondenti vi vengano instradati, poi premi il pulsante Test del contact point. Un alert attivo chiamato HighCPU con l'etichetta severity="critical" appare come [firing] HighCPU (critical). Quando si risolve, arriva la stessa push con resolved tra parentesi quadre.
Tre note. La parte severity resta vuota se le tue regole non impostano quell'etichetta. Il template legge solo il primo alert di un gruppo (alerts.0), quindi se una notifica raggruppa più alert, vedi solo il riepilogo del primo. E il periodo di pending di ogni regola (per esempio 5 minuti) è il modo più economico per evitare che una metrica instabile svegli il telefono ogni minuto. La guida Grafana copre altri campi.
Uptime Kuma
Uptime Kuma invia un webhook a ogni cambio di stato. Aggiungi una notifica di tipo Webhook, imposta Post URL sul tuo URL di ricezione e mantieni il preset JSON come corpo della richiesta.
In Pocket Alert, usa %msg% come template. msg è l'unico campo presente in ogni richiesta che Uptime Kuma invia, inclusi gli avvisi sui certificati e i messaggi di test, e si legge già come "[Website] [🔴 Down] timeout of 4000ms exceeded". Imposta il livello predefinito del webhook su high.
Con il corpo preset, i ripristini arrivano con la stessa intensità dei guasti, perché Uptime Kuma non aggiunge da solo un campo level. La guida Uptime Kuma mostra un corpo personalizzato che invia high per down e low per up.
n8n
In un workflow n8n, aggiungi un nodo HTTP Request dopo il passaggio che rileva il problema:
- Method:
POST - URL:
https://api.pocketalert.app/v1/messages - Authentication: Generic Credential Type, poi Header Auth. Nome
Token, valore la tua chiave API. - Send Body: attivo, Body Content Type JSON, Specify Body Using JSON, con un'espressione che costruisce l'intero oggetto:
{{ JSON.stringify({
title: 'Disk almost full on ' + $json.host,
message: $json.detail,
level: 'high'
}) }}
JSON.stringify esegue l'escape di virgolette e a capo nei valori, cosa che un semplice "{{ $json.detail }}" dentro una stringa JSON non fa. Per i fallimenti di tutti i workflow, configura un error workflow che parte da un Error Trigger: il nome del workflow fallito è in $json.workflow.name e l'errore in $json.execution.error.message. La guida n8n include un workflow pronto da importare.
Controlli pianificati e ricorrenti
I cron job falliscono in silenzio, ed è il momento peggiore per perdere un alert. Metti l'alert nel job stesso:
POCKETALERT_API_KEY=YOUR_API_KEY
PATH=/usr/local/bin:/usr/bin:/bin
0 3 * * * pocketalert exec -t "Nightly backup" -- /opt/scripts/backup.sh
Cron non carica il profilo della shell, quindi le due righe in alto danno al job la chiave e un PATH che include la CLI. Un'esecuzione riuscita arriva come "✓ Nightly backup" al livello predefinito. Una fallita arriva come "✗ Nightly backup (exit 1)" con livello high, con le ultime righe di output nel messaggio. Aggiungi --on failure se vuoi essere avvisato solo dei fallimenti.
exec ti dice quando un job fallisce, non quando non viene eseguito. Per questo, abbinalo a un dead man's switch, come nella guida al monitoraggio dei cron job.
Se non sei sicuro di una pianificazione, incollala nel tool gratuito per le espressioni cron. Scompone ogni campo in un linguaggio semplice ed elenca i prossimi orari di esecuzione. Gli orari indicati usano il fuso orario del tuo browser, che può essere diverso da quello del server.
Livelli di priorità e avvisi critici
Sono disponibili cinque livelli, dal più silenzioso al più rumoroso:
| Livello | Valore | Su iPhone | Uso tipico |
|---|---|---|---|
silent | -2 | Nessun suono, direttamente nel Centro notifiche | Eventi "risolti", log che potresti leggere più tardi |
low | -1 | Passiva, non accende lo schermo | Informativo |
default | 0 | Notifica normale con suono | Esiti di routine, come un backup completato |
high | 1 | Urgente, supera Full immersion | Richiede attenzione a breve |
critical | 2 | Avviso critico, suona anche con il silenzioso attivo | Richiede attenzione subito. Solo piani a pagamento |
Nel piano gratuito, un messaggio critical viene consegnato come high. Arriva comunque subito come urgente, ma rispetta l'interruttore silenzioso.
Una mappatura ragionevole per un alert attivo e la sua risoluzione:
- attivo:
high, oppurecriticalper le poche cose per cui vale la pena svegliarsi - risolto:
silent
Impostalo con il livello predefinito del webhook, oppure con un campo level nel payload quando la tua sorgente può inviarlo.
Checklist: assicurati che l'alert arrivi
- Consenti le notifiche per l'app Pocket Alert nelle Impostazioni di iOS, incluse le Notifiche urgenti e, con un piano a pagamento, gli Avvisi critici.
- Testa con Full immersion attiva. Attiva la modalità Full immersion che usi, invia un test
highcon il comando curl qui sopra e verifica che arrivi. Se non arriva, controlla le impostazioni di notifica dell'app per quella Full immersion. - Verifica che la chiamata sia arrivata a Pocket Alert. I messaggi API compaiono nella cronologia dei messaggi nell'app e nella console web. Le chiamate webhook, comprese quelle rifiutate, compaiono nel log delle richieste di quel webhook. Se la chiamata c'è, il problema è sul telefono. Se non c'è, il problema è nella tua sorgente.
- Controlla i log della sorgente per la richiesta in uscita: URL, codice di stato e corpo della risposta.
- Tieni d'occhio il limite giornaliero. Il piano gratuito consente 50 notifiche al giorno. Un controllo instabile può esaurirle in un'ora, quindi regola soglie e periodi di pending prima di scalare.
pocketalert usagemostra quante ne hai ancora oggi.
Se un alert continua a non arrivare, segui i passaggi in ordine: log della sorgente, poi cronologia di Pocket Alert, poi impostazioni di livello e dispositivo. Questo ordine isola rapidamente il punto che non funziona.
FAQ
Posso inviare notifiche push a un iPhone senza una configurazione Apple developer mia?
Sì. Un servizio hosted che è già collegato ad APNs gestisce il lato Apple. Invii una richiesta HTTP con la tua chiave API e il servizio la consegna alla sua app per iPhone. Gestire un mittente proprio richiede chiavi di firma, la registrazione di un'app e un'app iOS tua.
Perché i miei alert self-hosted arrivano in ritardo o non arrivano affatto?
Di solito è una di tre cose: le notifiche non sono consentite per l'app, la Full immersion attiva trattiene l'alert in base al suo livello, oppure la richiesta non ha mai raggiunto il servizio. Controlla per prima cosa la cronologia dei messaggi o il log del webhook per capire quale delle tre vale.
Gli alert arrivano quando Full immersion è attiva?
I messaggi high arrivano come urgenti, che possono superare Full immersion una volta consentite le notifiche. I messaggi critical sui piani a pagamento vanno oltre e suonano anche con il telefono silenziato. I livelli più bassi aspettano. Testa la tua configurazione di Full immersion prima di farci affidamento.
C'è un piano gratuito?
Sì. Il piano gratuito include 50 notifiche al giorno, 1 dispositivo, 1 applicazione e 1 webhook. Sul piano gratuito i messaggi critici vengono consegnati con priorità alta.
Prossimi passi
Puoi avere il primo alert su iPhone in circa cinque minuti:
- Registrati e installa l'app sul tuo iPhone.
- Crea una chiave API su chiavi API.
- Esegui il comando curl di questa guida.
Quando funziona, collega una sorgente reale: un contact point Grafana, una notifica Uptime Kuma o un cron job. Per altre sorgenti da homelab, vedi alert per homelab e la guida Proxmox. Per altre integrazioni, vedi notifiche webhook e alert Grafana. Se stai confrontando le opzioni, la pagina delle alternative illustra le differenze.