# Notifiche push affidabili su iPhone da uno stack self-hosted

> Perché le notifiche push su iPhone da un homelab sono difficili, come è fatto un percorso affidabile e come collegare Grafana, Uptime Kuma, n8n, cron job e script shell ad avvisi urgenti e critici sul tuo telefono.

*04.11.2026*

<!-- source: https://pocketalert.app/it/blog/self-hosted-iphone-push-notifications -->

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](/blog/how-push-notifications-work-apns-fcm).

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

1. **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.
2. **Le notifiche urgenti possono superare Full immersion.** In Pocket Alert, i messaggi `high` arrivano come urgenti. I livelli più bassi aspettano la fine della Full immersion.
3. **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 `critical` sui 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:

<div class="cmp-table-wrap">
<table class="cmp-table">
<thead><tr><th>Il tuo stack fa</th><th>Pocket Alert fa</th></tr></thead>
<tbody>
<tr><td>Rileva il guasto e decide cosa conta</td><td>Riceve la richiesta e verifica la tua chiave API o l'URL del webhook</td></tr>
<tr><td>Formatta il testo, oppure invia il proprio JSON</td><td>Mappa i campi, imposta il livello di priorità e consegna ad APNs</td></tr>
<tr><td>Invia l'evento una volta, quando accade</td><td>Invia a tutti i dispositivi dell'account, oppure al dispositivo che indichi</td></tr>
<tr><td>Tiene i propri log</td><td>Conserva la cronologia dei messaggi e un log delle richieste per ogni webhook, così puoi vedere cosa è arrivato e cosa è fallito</td></tr>
</tbody>
</table>
</div>

## Invia il primo alert con curl

Registrati su [pocketalert.app/signup](/signup), apri [chiavi API](/account/apikeys) 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:

```bash
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`. Rifiuta `application/x-www-form-urlencoded`, che è ciò che invia `curl -d` se non imposti l'header. Usa `-H "Content-Type: application/json"` con un corpo JSON, oppure `-F` per i campi di un form.
- **`title` e `message` sono obbligatori.** Tutto il resto è facoltativo.
- **Ometti `device_id` per 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](/tools/cli) è il modo più rapido per collegare gli alert agli script esistenti. Installala con lo script shell, Homebrew o Go:

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

```bash
pocketalert send "Deploy finished" "v2.4.0 is live" --level high
```

Invia direttamente l'output di un comando in un alert:

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

```bash
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](/webhooks): 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:

```json
{
  "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](/tools/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](/blog/how-to-integrate-grafana-into-pocketalert) 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](/blog/uptime-kuma-notifications) 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](/blog/n8n-push-notifications) 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:

```bash
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](/blog/cron-job-monitoring-healthchecks).

Se non sei sicuro di una pianificazione, incollala nel [tool gratuito per le espressioni cron](/tools/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:

<div class="cmp-table-wrap">
<table class="cmp-table">
<thead><tr><th>Livello</th><th>Valore</th><th>Su iPhone</th><th>Uso tipico</th></tr></thead>
<tbody>
<tr><th><code>silent</code></th><td>-2</td><td>Nessun suono, direttamente nel Centro notifiche</td><td>Eventi "risolti", log che potresti leggere più tardi</td></tr>
<tr><th><code>low</code></th><td>-1</td><td>Passiva, non accende lo schermo</td><td>Informativo</td></tr>
<tr><th><code>default</code></th><td>0</td><td>Notifica normale con suono</td><td>Esiti di routine, come un backup completato</td></tr>
<tr><th><code>high</code></th><td>1</td><td>Urgente, supera Full immersion</td><td>Richiede attenzione a breve</td></tr>
<tr><th><code>critical</code></th><td>2</td><td>Avviso critico, suona anche con il silenzioso attivo</td><td>Richiede attenzione subito. Solo piani a pagamento</td></tr>
</tbody>
</table>
</div>

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`, oppure `critical` per 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

1. **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.
2. **Testa con Full immersion attiva.** Attiva la modalità Full immersion che usi, invia un test `high` con il comando curl qui sopra e verifica che arrivi. Se non arriva, controlla le impostazioni di notifica dell'app per quella Full immersion.
3. **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.
4. **Controlla i log della sorgente** per la richiesta in uscita: URL, codice di stato e corpo della risposta.
5. **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 usage` mostra 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:

1. [Registrati](/signup) e installa l'app sul tuo iPhone.
2. Crea una chiave API su [chiavi API](/account/apikeys).
3. 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](/use-cases/homelab-alerts) e la [guida Proxmox](/blog/proxmox-alerts). Per altre integrazioni, vedi [notifiche webhook](/use-cases/webhook-notifications) e [alert Grafana](/use-cases/grafana-alerts). Se stai confrontando le opzioni, la [pagina delle alternative](/alternatives) illustra le differenze.
