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

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.
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:
- 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.
- Zeitkritische Mitteilungen können den Fokus durchbrechen. In Pocket Alert kommen
high-Nachrichten als zeitkritisch an. Niedrigere Stufen warten, bis der Fokus endet. - 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:
| Dein Stack macht | Pocket Alert macht |
|---|---|
| Erkennt den Ausfall und entscheidet, was wichtig ist | Nimmt die Anfrage entgegen und prüft deinen API-Schlüssel oder deine Webhook-URL |
| Formatiert den Text oder sendet eigenes JSON | Ordnet Felder zu, setzt die Prioritätsstufe und liefert an APNs aus |
| Sendet das Ereignis einmal, wenn es passiert | Sendet an alle Geräte des Accounts oder an das Gerät, das du angibst |
| Führt eigene Logs | Speichert den Nachrichtenverlauf und ein Anfrage-Log pro Webhook, damit du siehst, was angekommen und was fehlgeschlagen ist |
Den ersten Alert mit curl senden
Registriere dich unter pocketalert.app/signup, öffne API-Schlüssel 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:
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 lehntapplication/x-www-form-urlencodedab, dascurl -dsendet, wenn du den Header weglässt. Verwende-H "Content-Type: application/json"mit einem JSON-Body oder-Ffür Formularfelder. titleundmessagesind Pflichtfelder. Alles andere ist optional.- Lass
device_idweg, 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 ist der schnellste Weg, Alerts in bestehende Skripte einzubinden. Installiere sie per Shell-Skript, Homebrew oder 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
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:
pocketalert send "Deploy finished" "v2.4.0 is live" --level high
Befehlsausgabe direkt an einen Alert weiterleiten:
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:
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 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:
{
"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, 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 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 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 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:
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.
Wenn du bei einem Zeitplan unsicher bist, füge ihn in das kostenlose Cron-Ausdruck-Tool 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:
| Stufe | Wert | Auf dem iPhone | Typischer Einsatz |
|---|---|---|---|
silent | -2 | Kein Ton, direkt in die Mitteilungszentrale | „Resolved“-Ereignisse, Logs, die du später liest |
low | -1 | Passiv, schaltet den Bildschirm nicht ein | Informativ |
default | 0 | Normale Benachrichtigung mit Ton | Routineergebnisse, etwa ein fertiges Backup |
high | 1 | Zeitkritisch, durchbricht den Fokus | Braucht bald Aufmerksamkeit |
critical | 2 | Kritische Warnung, ertönt auch bei Stummschaltung | Braucht jetzt Aufmerksamkeit. Nur bezahlte Tarife |
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, odercriticalfü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
- Erlaube Mitteilungen für die Pocket-Alert-App in den iOS-Einstellungen, einschließlich Zeitkritische Mitteilungen und, bei einem bezahlten Tarif, Kritische Mitteilungen.
- 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. - 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.
- Prüfe die Logs deiner Quelle auf die ausgehende Anfrage: URL, Statuscode und Antwort-Body.
- 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 usagezeigt, 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:
- Registriere dich und installiere die App auf deinem iPhone.
- Erstelle unter API-Schlüssel einen API-Schlüssel.
- 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 und im Proxmox-Guide. Für weitere Integrationen siehe Webhook-Benachrichtigungen und Grafana-Alerts. Wenn du Optionen vergleichst, zeigt die Alternativen-Seite die Unterschiede.