# Zuverlässige Push-Benachrichtigungen auf dem iPhone aus einem selbst gehosteten Stack

> Warum Push-Benachrichtigungen auf dem iPhone aus dem Homelab schwierig sind, wie ein zuverlässiger Weg aussieht und wie du Grafana, Uptime Kuma, n8n, Cronjobs und Shell-Skripte mit zeitkritischen und kritischen Warnungen auf dein Handy verbindest.

*04.11.2026*

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

Dein Grafana-Alert feuert um 3 Uhr nachts. Deine Server-Logs zeigen, dass der Webhook-Aufruf erfolgreich war. Dein iPhone bleibt stumm. Selbst gehostetes Monitoring erkennt Ausfälle gut. Schwierig wird es meist, wenn die Nachricht tatsächlich auf dem Handy ankommen soll.

Dieser Guide erklärt, warum Push-Benachrichtigungen auf dem iPhone aus einem selbst gehosteten Stack schwierig sind, wie ein zuverlässiger Weg aussieht und wie du Grafana, Uptime Kuma, n8n, Cronjobs und Shell-Skripte anbindest. Den ersten funktionierenden Alert hast du in etwa fünf Minuten.

## Warum iOS-Push in selbst gehosteten Setups scheitert

### Nur APNs erreicht ein iPhone

Jede Push-Benachrichtigung an ein iPhone läuft über den Apple Push Notification Service (APNs). Dein Server kann keine Verbindung zum Handy öffnen und Daten direkt senden. Das Handy hält eine langlebige Verbindung zu Apple offen. Dein Server schickt jede Nachricht per HTTP/2 an APNs, authentifiziert mit einem Schlüssel aus deinem Apple-Developer-Account. APNs liefert sie dann über die bestehende Verbindung des Handys aus.

Dein Stack braucht also einen APNs-fähigen Absender dazwischen. Das Handy fragt deinen Server nie ab, deshalb hat ein einfacher Webhook-Endpunkt im LAN nichts, wohin er zustellen könnte. Mehr zum Zustellweg findest du unter [so erreichen Push-Benachrichtigungen ein iPhone](/blog/how-push-notifications-work-apns-fcm).

### Einen eigenen Absender zu betreiben ist aufwendiger, als es aussieht

Du kannst APNs selbst ansprechen. Dafür brauchst du einen Signierschlüssel (eine `.p8`-Datei für Token-Authentifizierung, die nicht jährlich abläuft, oder ein TLS-Client-Zertifikat pro App, das abläuft), eine registrierte App, einen Speicher für Gerätetokens und Code, der APNs-Fehler und Wiederholungen behandelt. Außerdem brauchst du eine iOS-App, die das Gerät registriert und den Alert anzeigt. Jedes Teil ist für sich machbar. Die eigentliche Arbeit ist, alles über Schlüsselrotation und Änderungen der Apple-Richtlinien hinweg funktionsfähig zu halten.

Die meisten Selbst-Hoster brauchen das Ergebnis, nicht die Technik dahinter. Ein gehosteter Dienst, der die APNs-Seite bereits betreibt, hält deinen Stack einfach: eine HTTP-Anfrage pro Alert.

### Fokus, Stummschaltung und Unterbrechungsstufen

iOS entscheidet anhand der Unterbrechungsstufe, deiner Fokus-Modi und der App-Einstellungen, wie laut eine Benachrichtigung zugestellt wird. Für Alerts sind drei Dinge wichtig:

1. **Mitteilungen müssen für die App erlaubt sein.** Prüfe das zuerst in den iOS-Einstellungen. Eine stummgeschaltete App zeigt deinen Alert nie an, egal wie sich der Server verhält.
2. **Zeitkritische Mitteilungen können den Fokus durchbrechen.** In Pocket Alert kommen `high`-Nachrichten als zeitkritisch an. Niedrigere Stufen warten, bis der Fokus endet.
3. **Kritische Warnungen ignorieren den Stummschalter und „Nicht stören“.** Dafür braucht es eine spezielle Berechtigung, die Apple nach Prüfung vergibt. Pocket Alert hat sie: `critical`-Nachrichten spielen in bezahlten Tarifen auch dann einen Ton ab, wenn das Handy stummgeschaltet ist, sofern du Critical Alerts für die App erlaubt hast. Wenn du diese Berechtigung deaktiviert hast, kommen sie als zeitkritisch an.

Im Abschnitt zu den Prioritäten unten erfährst du, wie du die Stufe setzt.

## So sieht ein zuverlässiges Setup aus

Dein Stack erkennt ein Problem und sendet eine HTTP-Anfrage. Ein gehosteter Dienst übernimmt den Rest:

```
Grafana / Uptime Kuma / n8n / cron + CLI
        │  HTTPS (API call or webhook)
        ▼
Pocket Alert  ──►  APNs  ──►  iPhone (Pocket Alert app)
```

Die Aufgaben verteilen sich so:

<div class="cmp-table-wrap">
<table class="cmp-table">
<thead><tr><th>Dein Stack macht</th><th>Pocket Alert macht</th></tr></thead>
<tbody>
<tr><td>Erkennt den Ausfall und entscheidet, was wichtig ist</td><td>Nimmt die Anfrage entgegen und prüft deinen API-Schlüssel oder deine Webhook-URL</td></tr>
<tr><td>Formatiert den Text oder sendet eigenes JSON</td><td>Ordnet Felder zu, setzt die Prioritätsstufe und liefert an APNs aus</td></tr>
<tr><td>Sendet das Ereignis einmal, wenn es passiert</td><td>Sendet an alle Geräte des Accounts oder an das Gerät, das du angibst</td></tr>
<tr><td>Führt eigene Logs</td><td>Speichert den Nachrichtenverlauf und ein Anfrage-Log pro Webhook, damit du siehst, was angekommen und was fehlgeschlagen ist</td></tr>
</tbody>
</table>
</div>

## Den ersten Alert mit curl senden

Registriere dich unter [pocketalert.app/signup](/signup), öffne [API-Schlüssel](/account/apikeys) und klicke auf **Neuen Schlüssel erstellen**. Der Schlüssel wird nur einmal angezeigt, kopiere ihn also an einen sicheren Ort.

Speichere ihn in einer Umgebungsvariable und sende eine Nachricht:

```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"
  }'
```

Ein erfolgreicher Aufruf liefert JSON mit `tid`, `title`, `message`, `application`, `device` und `created_at` zurück. Behalte die `tid`, wenn du eine Push-Nachricht später einer Log-Zeile zuordnen willst.

Drei Dinge sorgen oft für Probleme:

- **Setze den Content-Type.** Die API akzeptiert JSON oder `multipart/form-data`. Sie lehnt `application/x-www-form-urlencoded` ab, das `curl -d` sendet, wenn du den Header weglässt. Verwende `-H "Content-Type: application/json"` mit einem JSON-Body oder `-F` für Formularfelder.
- **`title` und `message` sind Pflichtfelder.** Alles andere ist optional.
- **Lass `device_id` weg, um alle Geräte** des Accounts zu erreichen. Füge es hinzu, wenn du mehrere Handys hast und ein bestimmtes ansprechen willst.

## Alerts von der Kommandozeile senden

Die [Pocket-Alert-CLI](/tools/cli) ist der schnellste Weg, Alerts in bestehende Skripte einzubinden. Installiere sie per Shell-Skript, Homebrew oder 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
```

Führe einmal `pocketalert auth` aus und füge deinen Schlüssel ein. Der Schlüssel wird in `~/.pocketalert/config.json` gespeichert, das nur du lesen kannst. Auf Servern, in Containern und in CI setzt du stattdessen `POCKETALERT_API_KEY`.

Nachricht senden:

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

Befehlsausgabe direkt an einen Alert weiterleiten:

```bash
df -h | pocketalert send "Disk report" --level default
```

Oder umschließe einen Befehl mit `exec`. Er führt den Befehl wie gewohnt aus und sendet danach eine Push-Benachrichtigung mit Exit-Status, Dauer und den letzten Ausgabezeilen. Den Exit-Code gibt er unverändert weiter:

```bash
pocketalert exec -t "Database dump" -- ./dump.sh
```

Mit `-q` gibt der Befehl nur die Nachrichten-ID aus, was sich praktisch für Skripte eignet. Füge `--json` zu einem beliebigen Befehl hinzu, um maschinenlesbare Ausgabe zu erhalten.

## Webhooks mit Feldzuordnung

Wenn deine Quelle bereits JSON sendet, etwa Grafana, Uptime Kuma oder ein eigener Dienst, musst du keinen Absender selbst schreiben. Lege im Dashboard unter [Webhooks](/webhooks) einen Webhook an. Pocket Alert gibt dir dann eine Empfangs-URL wie `https://p4a.me/wh/1234abcd`. Der Slug ist nicht erratbar, und jede URL gehört zu genau einem Webhook und einer Anwendung. Richte deine Quelle mit `POST` auf diese URL.

Die Push-Benachrichtigung erscheint mit dem Titel „Webhook“ plus dem Namen des Webhooks. Benenne ihn deshalb nach der Quelle, zum Beispiel **Grafana**. Die Nachrichtenvorlage zieht Werte aus dem eingehenden JSON über GJSON-Pfade:

- `%object.field%` für verschachtelte Felder
- `%items.0.name%` für Array-Elemente
- `%users.#%` für eine Anzahl
- `*` als gesamte Vorlage sendet den kompletten Body

Eine Vorlage für eine eingehende Nutzlast wie diese:

```json
{
  "service": "api-gateway",
  "check": "tls-expiry",
  "state": "warning",
  "detail": "certificate expires in 6 days"
}
```

könnte so aussehen:

```
[%state%] %service%: %check%
%detail%
```

Ein Platzhalter, dessen Pfad fehlt, wird als leerer String ausgegeben. Ein Tippfehler zeigt sich also als Lücke im Text und nicht als Fehler.

Erfasse vor dem Schreiben einer Vorlage die echte Nutzlast. Öffne den [Webhook-Tester](/tools/webhook), kopiere die Test-URL und richte deine Quelle darauf aus. Der Tester zeigt Methode, Header und Body, sodass du Pfade passend zu dem schreiben kannst, was deine Quelle tatsächlich sendet. Sende keine Produktions-Geheimnisse an eine öffentliche Test-URL. Wer die URL kennt, kann lesen, was dort ankommt.

Die Priorität lässt sich auf zwei Wegen setzen. Lege eine Standardstufe am Webhook fest oder nimm ein `level`-Feld auf oberster Ebene in die Nutzlast auf, das den Standard überschreibt. Gültige Werte sind `silent`, `low`, `default`, `high` und `critical` oder die Zahlen `-2` bis `2`. Ein ungültiges `level` wird ignoriert, dann gilt der Standard des Webhooks.

## Integrationen

### Grafana-Alerts

Lege im Dashboard einen Webhook namens **Grafana** mit dieser Nachrichtenvorlage an:

```
[%status%] %commonLabels.alertname% (%commonLabels.severity%)
%alerts.0.annotations.summary%
```

Kopiere die Empfangs-URL. Gehe in Grafana zu **Alerting → Contact points → Add contact point**, wähle die Integration **Webhook** und setze:

```
Integration: Webhook
URL:         https://p4a.me/wh/1234abcd
Method:      POST
```

Hänge den Contact Point an eine Notification Policy, damit passende Alerts dorthin geleitet werden, und drücke dann den Button **Test** des Contact Points. Ein feuernder Alert namens `HighCPU` mit dem Label `severity="critical"` erscheint als `[firing] HighCPU (critical)`. Wenn er sich wieder erholt, kommt dieselbe Push-Benachrichtigung mit `resolved` in den Klammern an.

Drei Hinweise. Der Teil `severity` bleibt leer, solange deine Regeln dieses Label nicht setzen. Die Vorlage liest nur den ersten Alert einer Gruppe (`alerts.0`). Wenn eine Benachrichtigung mehrere Alerts bündelt, siehst du also nur die erste Zusammenfassung. Und die Pending-Dauer jeder Regel (zum Beispiel 5 Minuten) ist der günstigste Weg, um zu verhindern, dass eine schwankende Metrik dein Handy jede Minute weckt. Der [Grafana-Guide](/blog/how-to-integrate-grafana-into-pocketalert) behandelt weitere Felder.

### Uptime Kuma

Uptime Kuma sendet bei jeder Statusänderung einen Webhook. Füge eine Benachrichtigung vom Typ **Webhook** hinzu, setze **Post URL** auf deine Empfangs-URL und behalte die JSON-Voreinstellung als Request-Body.

Verwende in Pocket Alert `%msg%` als Vorlage. `msg` ist das einzige Feld, das in jeder Anfrage von Uptime Kuma vorhanden ist, auch bei Zertifikatswarnungen und Testnachrichten, und es liest sich bereits wie „[Website] [🔴 Down] timeout of 4000ms exceeded“. Setze die Standardstufe des Webhooks auf `high`.

Mit der Voreinstellung für den Body kommen Erholungen genauso laut an wie Ausfälle, weil Uptime Kuma von sich aus kein `level`-Feld hinzufügt. Der [Uptime-Kuma-Guide](/blog/uptime-kuma-notifications) zeigt einen eigenen Body, der bei Ausfall `high` und bei Erholung `low` sendet.

### n8n

Füge in einem n8n-Workflow nach dem Schritt, der ein Problem erkennt, einen **HTTP Request**-Knoten hinzu:

- **Method:** `POST`
- **URL:** `https://api.pocketalert.app/v1/messages`
- **Authentication:** Generic Credential Type, dann Header Auth. Name `Token`, Wert dein API-Schlüssel.
- **Send Body:** an, **Body Content Type** JSON, **Specify Body** Using JSON, mit einem Ausdruck, der das gesamte Objekt erzeugt:

```
{{ JSON.stringify({
  title: 'Disk almost full on ' + $json.host,
  message: $json.detail,
  level: 'high'
}) }}
```

`JSON.stringify` escaped Anführungszeichen und Zeilenumbrüche in den Werten. Das leistet `"{{ $json.detail }}"` innerhalb eines JSON-Strings nicht. Für Fehler aus allen Workflows richtest du einen Error-Workflow ein, der mit einem **Error Trigger** startet: Der Name des fehlgeschlagenen Workflows steht in `$json.workflow.name`, die Fehlermeldung in `$json.execution.error.message`. Der [n8n-Guide](/blog/n8n-push-notifications) enthält einen fertigen Workflow zum Importieren.

## Geplante und wiederkehrende Prüfungen

Cronjobs schlagen stillschweigend fehl, und genau dann ist ein verpasster Alert am schlimmsten. Setze den Alert direkt in den Job:

```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 lädt dein Shell-Profil nicht. Deshalb geben dir die zwei Zeilen oben dem Job den Schlüssel und einen `PATH`, der die CLI enthält. Ein erfolgreicher Lauf kommt als „✓ Nightly backup“ mit der Standardstufe an. Ein fehlgeschlagener als „✗ Nightly backup (exit 1)“ mit `high`, und die letzten Ausgabezeilen stehen in der Nachricht. Füge `--on failure` hinzu, wenn du nur über Fehler informiert werden willst.

`exec` meldet, wenn ein Job fehlschlägt, aber nicht, wenn er gar nicht läuft. Dafür kombinierst du es mit einem Dead-Man's-Switch, wie im [Guide zur Überwachung von Cronjobs](/blog/cron-job-monitoring-healthchecks).

Wenn du bei einem Zeitplan unsicher bist, füge ihn in das kostenlose [Cron-Ausdruck-Tool](/tools/cron) ein. Es übersetzt jedes Feld in verständliches Deutsch und listet die nächsten Ausführungszeiten auf. Die Zeiten richten sich nach der Zeitzone deines Browsers, die von der Serverzeit abweichen kann.

## Prioritätsstufen und kritische Alerts

Es gibt fünf Stufen, von leise bis laut:

<div class="cmp-table-wrap">
<table class="cmp-table">
<thead><tr><th>Stufe</th><th>Wert</th><th>Auf dem iPhone</th><th>Typischer Einsatz</th></tr></thead>
<tbody>
<tr><th><code>silent</code></th><td>-2</td><td>Kein Ton, direkt in die Mitteilungszentrale</td><td>„Resolved“-Ereignisse, Logs, die du später liest</td></tr>
<tr><th><code>low</code></th><td>-1</td><td>Passiv, schaltet den Bildschirm nicht ein</td><td>Informativ</td></tr>
<tr><th><code>default</code></th><td>0</td><td>Normale Benachrichtigung mit Ton</td><td>Routineergebnisse, etwa ein fertiges Backup</td></tr>
<tr><th><code>high</code></th><td>1</td><td>Zeitkritisch, durchbricht den Fokus</td><td>Braucht bald Aufmerksamkeit</td></tr>
<tr><th><code>critical</code></th><td>2</td><td>Kritische Warnung, ertönt auch bei Stummschaltung</td><td>Braucht jetzt Aufmerksamkeit. Nur bezahlte Tarife</td></tr>
</tbody>
</table>
</div>

Im kostenlosen Tarif wird eine `critical`-Nachricht mit `high` zugestellt. Sie kommt trotzdem sofort als zeitkritisch an, respektiert aber den Stummschalter.

Eine sinnvolle Zuordnung für einen feuernden Alert und seine Auflösung:

- firing: `high`, oder `critical` für die wenigen Dinge, die es wert sind, dich zu wecken
- resolved: `silent`

Setze das über die Standardstufe des Webhooks oder über ein `level`-Feld in der Nutzlast, wenn deine Quelle eines senden kann.

## Checkliste: Sicherstellen, dass dein Alert ankommt

1. **Erlaube Mitteilungen** für die Pocket-Alert-App in den iOS-Einstellungen, einschließlich Zeitkritische Mitteilungen und, bei einem bezahlten Tarif, Kritische Mitteilungen.
2. **Teste mit eingeschaltetem Fokus.** Aktiviere den Fokus-Modus, den du nutzt, sende mit dem curl-Befehl oben eine `high`-Testnachricht und prüfe, ob sie durchkommt. Falls nicht, kontrolliere die Benachrichtigungseinstellungen der App für diesen Fokus.
3. **Prüfe, ob der Aufruf Pocket Alert erreicht hat.** API-Nachrichten erscheinen im Nachrichtenverlauf der App und im Web-Dashboard. Webhook-Aufrufe, auch abgelehnte, erscheinen im Anfrage-Log des jeweiligen Webhooks. Wenn der Aufruf dort steht, liegt das Problem auf dem Handy. Wenn nicht, liegt es in deiner Quelle.
4. **Prüfe die Logs deiner Quelle** auf die ausgehende Anfrage: URL, Statuscode und Antwort-Body.
5. **Behalte das Tageslimit im Blick.** Der kostenlose Tarif erlaubt 50 Benachrichtigungen pro Tag. Eine schwankende Prüfung kann das in einer Stunde aufbrauchen. Stelle Schwellenwerte und Pending-Dauern deshalb ein, bevor du skalierst. `pocketalert usage` zeigt, wie viele heute noch übrig sind.

Wenn ein Alert trotzdem nicht ankommt, arbeite die Schritte in dieser Reihenfolge ab: Log der Quelle, dann Verlauf in Pocket Alert, dann Stufe und Geräteeinstellungen. So findest du den fehlerhaften Abschnitt schnell.

## FAQ

**Kann ich Push-Benachrichtigungen an ein iPhone senden, ohne ein eigenes Apple-Developer-Setup?**
Ja. Ein gehosteter Dienst, der bereits mit APNs verbunden ist, übernimmt die Apple-Seite. Du sendest eine HTTP-Anfrage mit deinem API-Schlüssel, und der Dienst liefert sie an seine iPhone-App aus. Einen eigenen Absender zu betreiben erfordert Signierschlüssel, eine App-Registrierung und eine eigene iOS-App.

**Warum kommen meine selbst gehosteten Alerts verspätet oder gar nicht an?**
Meist liegt es an einem von drei Dingen: Mitteilungen sind für die App nicht erlaubt, der aktive Fokus hält die Stufe des Alerts zurück, oder die Anfrage hat den Dienst nie erreicht. Prüfe zuerst den Nachrichtenverlauf oder das Webhook-Log, um zu sehen, welcher Fall zutrifft.

**Kommen Alerts durch, wenn der Fokus aktiv ist?**
`high`-Nachrichten kommen als zeitkritisch an und können den Fokus durchbrechen, sobald Mitteilungen erlaubt sind. `critical`-Nachrichten in bezahlten Tarifen gehen weiter und ertönen auch bei stummgeschaltetem Handy. Niedrigere Stufen warten. Teste dein eigenes Fokus-Setup, bevor du dich darauf verlässt.

**Gibt es einen kostenlosen Tarif?**
Ja. Der kostenlose Tarif umfasst 50 Benachrichtigungen pro Tag, 1 Gerät, 1 Anwendung und 1 Webhook. Kritische Nachrichten werden im kostenlosen Tarif mit hoher Priorität zugestellt.

## Nächste Schritte

Deinen ersten iPhone-Alert hast du in etwa fünf Minuten:

1. [Registriere dich](/signup) und installiere die App auf deinem iPhone.
2. Erstelle unter [API-Schlüssel](/account/apikeys) einen API-Schlüssel.
3. Führe den curl-Befehl aus diesem Guide aus.

Sobald das funktioniert, verbinde eine echte Quelle: einen Grafana-Contact-Point, eine Uptime-Kuma-Benachrichtigung oder einen Cronjob. Weitere Quellen für dein Homelab findest du unter [Homelab-Alerts](/use-cases/homelab-alerts) und im [Proxmox-Guide](/blog/proxmox-alerts). Für weitere Integrationen siehe [Webhook-Benachrichtigungen](/use-cases/webhook-notifications) und [Grafana-Alerts](/use-cases/grafana-alerts). Wenn du Optionen vergleichst, zeigt die [Alternativen-Seite](/alternatives) die Unterschiede.
