Notifications push fiables sur iPhone depuis une stack auto-hébergée

Votre alerte Grafana se déclenche à 3 h du matin. Les journaux de votre serveur indiquent que l'appel webhook a réussi. Votre iPhone reste silencieux. La supervision auto-hébergée sait très bien détecter les pannes. Le plus difficile, pour la plupart des installations homelab, est de faire parvenir le message jusqu'au téléphone.
Ce guide explique pourquoi les notifications push sur iPhone depuis une stack auto-hébergée sont difficiles à mettre en place, à quoi ressemble un chemin fiable, et comment connecter Grafana, Uptime Kuma, n8n, les tâches cron et les scripts shell. La première alerte fonctionnelle prend environ cinq minutes.
Pourquoi les notifications push iOS échouent dans les installations auto-hébergées
Seul APNs peut atteindre un iPhone
Toute notification push vers un iPhone passe par Apple Push Notification service (APNs). Votre serveur ne peut pas ouvrir de connexion directe vers le téléphone ni lui envoyer des données. Le téléphone maintient une connexion longue durée avec Apple. Votre serveur envoie chaque message à APNs en HTTP/2, authentifié avec une clé issue de votre compte développeur Apple. APNs achemine ensuite le message via la connexion existante du téléphone.
Votre stack a donc besoin d'un expéditeur capable de parler à APNs. Le téléphone n'interroge jamais votre serveur : un simple point d'accès webhook sur votre réseau local n'a donc rien à lui transmettre. Pour mieux comprendre le chemin de livraison, consultez le fonctionnement des notifications push jusqu'à un iPhone.
Gérer votre propre expéditeur demande plus de travail qu'il n'y paraît
Vous pouvez dialoguer directement avec APNs. Il vous faut une clé de signature (un fichier .p8 pour l'authentification par jeton, qui n'expire pas chaque année, ou un certificat client TLS par application, qui expire), une application enregistrée, un moyen de stocker les jetons des appareils, et du code qui gère les erreurs et les nouvelles tentatives d'APNs. Il vous faut aussi une application iOS qui enregistre l'appareil et affiche l'alerte. Chaque élément est gérable isolément. Le vrai coût, c'est de les maintenir tous en fonctionnement lors des rotations de clés et des changements de politique d'Apple.
La plupart des auto-hébergeurs ont besoin du résultat, pas de la plomberie. Un service hébergé qui prend déjà en charge la partie APNs permet de garder une stack simple : une requête HTTP par alerte.
Concentration, mode silencieux et niveaux d'interruption
iOS décide du volume de livraison de chaque notification selon son niveau d'interruption, vos modes Concentration et les paramètres de l'application. Trois éléments sont importants pour les alertes :
- Les notifications doivent être autorisées pour l'application. Vérifiez-le en premier dans les Réglages d'iOS. Une application dont les notifications sont coupées n'affichera jamais votre alerte, quel que soit le comportement du serveur.
- Les notifications urgentes peuvent passer outre la Concentration. Dans Pocket Alert, les messages
higharrivent comme urgents. Les niveaux inférieurs attendent la fin de la Concentration. - Les alertes critiques ignorent l'interrupteur silencieux et le mode Ne pas déranger. Elles nécessitent une autorisation spéciale qu'Apple accorde après examen. Pocket Alert la possède : les messages
criticalsur les offres payantes jouent un son même lorsque le téléphone est en silencieux, à condition d'avoir autorisé les alertes critiques pour l'application. Si vous avez désactivé cette autorisation, ils arrivent comme notifications urgentes.
La section sur les priorités ci-dessous explique comment définir le niveau.
À quoi ressemble une configuration fiable
Votre stack détecte un problème et envoie une seule requête HTTP. Un service hébergé prend ensuite le relais :
Grafana / Uptime Kuma / n8n / cron + CLI
│ HTTPS (API call or webhook)
▼
Pocket Alert ──► APNs ──► iPhone (Pocket Alert app)
La répartition des tâches se présente ainsi :
| Votre stack fait | Pocket Alert fait |
|---|---|
| Détecte la panne et décide de son importance | Reçoit la requête et vérifie votre clé API ou l'URL de votre webhook |
| Met en forme le texte, ou envoie son propre JSON | Associe les champs, définit le niveau de priorité et livre à APNs |
| Envoie l'événement une seule fois, au moment où il se produit | Envoie à tous les appareils du compte, ou à l'appareil que vous indiquez |
| Conserve ses propres journaux | Conserve l'historique des messages et un journal des requêtes pour chaque webhook, afin de voir ce qui est arrivé et ce qui a échoué |
Envoyer votre première alerte avec curl
Créez un compte sur pocketalert.app/signup, ouvrez clés API et cliquez sur Create New Key. La clé n'est affichée qu'une seule fois : copiez-la dans un endroit sûr.
Stockez-la dans une variable d'environnement et envoyez un message :
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"
}'
Un appel réussi renvoie du JSON contenant tid, title, message, application, device et created_at. Conservez le tid si vous voulez retrouver plus tard la correspondance entre une notification push et une ligne de journal.
Trois points posent souvent problème :
- Définissez le Content-Type. L'API accepte le JSON ou
multipart/form-data. Elle refuseapplication/x-www-form-urlencoded, quecurl -denvoie lorsque vous omettez l'en-tête. Utilisez-H "Content-Type: application/json"avec un corps JSON, ou-Fpour des champs de formulaire. titleetmessagesont obligatoires. Tous les autres champs sont facultatifs.- Omettez
device_idpour atteindre tous les appareils du compte. Ajoutez-le lorsque vous avez plusieurs téléphones et que vous en voulez un en particulier.
Envoyer des alertes depuis la ligne de commande
La CLI Pocket Alert est le moyen le plus rapide d'intégrer des alertes dans vos scripts existants. Installez-la avec le script shell, Homebrew ou 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
Exécutez pocketalert auth une seule fois et collez votre clé. La clé est enregistrée dans ~/.pocketalert/config.json, lisible uniquement par vous. Sur les serveurs, les conteneurs et la CI, définissez plutôt POCKETALERT_API_KEY.
Envoyer un message :
pocketalert send "Deploy finished" "v2.4.0 is live" --level high
Envoyer directement la sortie d'une commande dans une alerte :
df -h | pocketalert send "Disk report" --level default
Ou encapsuler une commande avec exec. Elle exécute la commande normalement, puis envoie une seule notification push contenant le code de sortie, la durée et les dernières lignes de sortie, et transmet le code de sortie d'origine :
pocketalert exec -t "Database dump" -- ./dump.sh
Utilisez -q pour n'afficher que l'identifiant du message, pratique dans un script. Ajoutez --json à n'importe quelle commande pour obtenir une sortie lisible par une machine.
Webhooks avec mappage des champs
Lorsque votre source envoie déjà du JSON, comme Grafana, Uptime Kuma ou un service maison, vous n'avez pas besoin d'écrire d'expéditeur. Créez un webhook dans la console, à l'adresse Webhooks : Pocket Alert vous fournit une URL de réception du type https://p4a.me/wh/1234abcd. Le slug est impossible à deviner, et chaque URL est limitée à un seul webhook et une seule application. Configurez votre source pour envoyer une requête POST vers cette URL.
La notification arrive avec le titre « Webhook » suivi du nom du webhook. Donnez-lui donc le nom de la source, par exemple Grafana. Le modèle de message extrait les valeurs du JSON entrant grâce aux chemins GJSON :
%object.field%pour les champs imbriqués%items.0.name%pour les éléments d'un tableau%users.#%pour un nombre d'éléments*comme modèle complet envoie l'intégralité du corps
Par exemple, un modèle pour une charge utile entrante de ce type :
{
"service": "api-gateway",
"check": "tls-expiry",
"state": "warning",
"detail": "certificate expires in 6 days"
}
pourrait être :
[%state%] %service%: %check%
%detail%
Un espace réservé dont le chemin est absent est remplacé par une chaîne vide : une faute de frappe apparaît donc sous forme de trou dans le texte, et non sous forme d'erreur.
Avant d'écrire un modèle, capturez la charge utile réelle. Ouvrez le testeur de webhook, copiez l'URL de test et configurez votre source pour l'envoyer à cette adresse. Le testeur affiche la méthode, les en-têtes et le corps, ce qui vous permet d'écrire les chemins en fonction de ce que votre source envoie réellement. N'envoyez pas de secrets de production à une URL de test publique : quiconque connaît cette URL peut lire ce qui y arrive.
La priorité peut être définie de deux façons. Définissez un niveau par défaut sur le webhook, ou ajoutez un champ level de premier niveau dans la charge utile, qui remplace la valeur par défaut. Les valeurs valides sont silent, low, default, high et critical, ou les nombres -2 à 2. Un level invalide est ignoré, et la valeur par défaut du webhook s'applique.
Intégrations
Alertes Grafana
Dans la console, créez un webhook nommé Grafana avec ce modèle de message :
[%status%] %commonLabels.alertname% (%commonLabels.severity%)
%alerts.0.annotations.summary%
Copiez son URL de réception. Dans Grafana, allez dans Alerting → Contact points → Add contact point, choisissez l'intégration Webhook et définissez :
Integration: Webhook
URL: https://p4a.me/wh/1234abcd
Method: POST
Rattachez le point de contact à une politique de notification pour que les alertes correspondantes lui soient acheminées, puis appuyez sur le bouton Test du point de contact. Une alerte active nommée HighCPU avec le label severity="critical" apparaît sous la forme [firing] HighCPU (critical). Lorsqu'elle se résout, la même notification arrive avec resolved entre crochets.
Trois remarques. La partie severity reste vide si vos règles ne définissent pas ce label. Le modèle ne lit que la première alerte d'un groupe (alerts.0) : si une notification regroupe plusieurs alertes, vous ne voyez que le résumé de la première. Enfin, la période d'attente de chaque règle (par exemple 5 minutes) est le moyen le plus simple d'éviter qu'une métrique instable ne réveille votre téléphone toutes les minutes. Le guide Grafana détaille davantage de champs.
Uptime Kuma
Uptime Kuma envoie un webhook à chaque changement d'état. Ajoutez une notification de type Webhook, définissez Post URL sur votre URL de réception, et conservez le préréglage JSON comme corps de requête.
Dans Pocket Alert, utilisez %msg% comme modèle. msg est le seul champ présent dans chaque requête envoyée par Uptime Kuma, y compris les alertes de certificat et les messages de test, et il se lit déjà comme « [Website] [🔴 Down] timeout of 4000ms exceeded ». Définissez le niveau par défaut du webhook sur high.
Avec le corps prédéfini, les rétablissements arrivent avec la même intensité que les pannes, car Uptime Kuma n'ajoute pas de champ level de lui-même. Le guide Uptime Kuma montre un corps personnalisé qui envoie high pour une panne et low pour un rétablissement.
n8n
Dans un workflow n8n, ajoutez un nœud HTTP Request après l'étape qui détecte le problème :
- Method :
POST - URL :
https://api.pocketalert.app/v1/messages - Authentication : Generic Credential Type, puis Header Auth. Nom
Token, valeur votre clé API. - Send Body : activé, Body Content Type JSON, Specify Body Using JSON, avec une expression qui construit l'objet entier :
{{ JSON.stringify({
title: 'Disk almost full on ' + $json.host,
message: $json.detail,
level: 'high'
}) }}
JSON.stringify échappe les guillemets et les sauts de ligne dans les valeurs, ce que ne fait pas un simple "{{ $json.detail }}" placé dans une chaîne JSON. Pour les échecs de tous les workflows, configurez un workflow d'erreur qui démarre avec un Error Trigger : le nom du workflow en échec se trouve dans $json.workflow.name et l'erreur dans $json.execution.error.message. Le guide n8n propose un workflow prêt à importer.
Vérifications planifiées et récurrentes
Les tâches cron échouent en silence, ce qui est le pire moment pour rater une alerte. Placez l'alerte directement dans la tâche :
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 ne charge pas votre profil shell : les deux lignes du haut fournissent donc à la tâche la clé et un PATH qui inclut la CLI. Une exécution réussie arrive sous la forme « ✓ Nightly backup » au niveau par défaut. Une exécution en échec arrive sous la forme « ✗ Nightly backup (exit 1) » avec le niveau high, et les dernières lignes de sortie dans le message. Ajoutez --on failure si vous ne voulez être prévenu que des échecs.
exec vous informe lorsqu'une tâche échoue, pas lorsqu'elle ne s'exécute jamais. Pour ce cas, associez-la à un dead man's switch, comme dans le guide de supervision des tâches cron.
Si vous n'êtes pas sûr d'une planification, collez-la dans l'outil d'expressions cron gratuit. Il décode chaque champ en langage clair et liste les prochaines exécutions. Les heures de prochaine exécution utilisent le fuseau horaire de votre navigateur, qui peut différer de celui du serveur.
Niveaux de priorité et alertes critiques
Cinq niveaux sont disponibles, du plus discret au plus bruyant :
| Niveau | Valeur | Sur iPhone | Usage typique |
|---|---|---|---|
silent | -2 | Sans son, directement dans le Centre de notifications | Événements « résolus », journaux que vous pourrez lire plus tard |
low | -1 | Passive, n'allume pas l'écran | Informatif |
default | 0 | Notification normale avec son | Résultats courants, comme une sauvegarde terminée |
high | 1 | Urgente, passe outre la Concentration | Demande une attention rapide |
critical | 2 | Alerte critique, sonne même en silencieux | Demande une attention immédiate. Offres payantes uniquement |
Sur l'offre gratuite, un message critical est livré au niveau high. Il arrive toujours immédiatement comme notification urgente, mais il respecte l'interrupteur silencieux.
Un mappage raisonnable pour une alerte active et sa résolution :
- activation :
high, oucriticalpour les rares éléments qui justifient d'être réveillé - résolution :
silent
Définissez-le avec le niveau par défaut du webhook, ou avec un champ level dans la charge utile lorsque votre source peut en envoyer un.
Liste de contrôle : vérifier que votre alerte arrive
- Autorisez les notifications pour l'application Pocket Alert dans les Réglages d'iOS, y compris les Notifications urgentes et, avec une offre payante, les Alertes critiques.
- Testez avec la Concentration activée. Activez le mode Concentration que vous utilisez, envoyez un test
highavec la commande curl ci-dessus, et vérifiez qu'il passe. Sinon, contrôlez les paramètres de notification de l'application pour cette Concentration. - Vérifiez que l'appel a atteint Pocket Alert. Les messages API apparaissent dans l'historique des messages, dans l'application comme dans la console web. Les appels de webhook, y compris ceux qui ont été rejetés, apparaissent dans le journal des requêtes de ce webhook. Si l'appel y figure, le problème se trouve sur le téléphone. Sinon, le problème vient de votre source.
- Consultez les journaux de votre source pour la requête sortante : URL, code de statut et corps de la réponse.
- Surveillez la limite quotidienne. L'offre gratuite autorise 50 notifications par jour. Une vérification instable peut épuiser ce quota en une heure : ajustez donc les seuils et les périodes d'attente avant de monter en charge.
pocketalert usageindique combien il vous en reste pour aujourd'hui.
Si une alerte n'arrive toujours pas, parcourez les étapes dans l'ordre : journal de la source, puis historique de Pocket Alert, puis paramètres de niveau et d'appareil. Cet ordre isole rapidement le maillon défaillant.
FAQ
Puis-je envoyer des notifications push à un iPhone sans configuration Apple Developer personnelle ?
Oui. Un service hébergé déjà connecté à APNs gère la partie Apple. Vous envoyez une requête HTTP avec votre clé API, et le service la livre à son application iPhone. Gérer votre propre expéditeur demande des clés de signature, l'enregistrement d'une application et une application iOS dédiée.
Pourquoi mes alertes auto-hébergées arrivent-elles en retard, ou pas du tout ?
En général, pour l'une de ces trois raisons : les notifications ne sont pas autorisées pour l'application, la Concentration active retient le niveau de l'alerte, ou la requête n'a jamais atteint le service. Vérifiez d'abord l'historique des messages ou le journal du webhook pour identifier la cause.
Les alertes passent-elles lorsque la Concentration est activée ?
Les messages high arrivent comme notifications urgentes, qui peuvent passer outre la Concentration une fois les notifications autorisées. Les messages critical sur les offres payantes vont plus loin : ils sonnent même lorsque le téléphone est en silencieux. Les niveaux inférieurs attendent. Testez votre propre configuration de Concentration avant de vous y fier.
Existe-t-il une offre gratuite ?
Oui. L'offre gratuite comprend 50 notifications par jour, 1 appareil, 1 application et 1 webhook. Sur l'offre gratuite, les messages critiques sont livrés avec une priorité élevée.
Étapes suivantes
Vous pouvez recevoir votre première alerte sur iPhone en environ cinq minutes :
- Créez un compte et installez l'application sur votre iPhone.
- Créez une clé API dans clés API.
- Exécutez la commande curl de ce guide.
Une fois cela fonctionnel, connectez une vraie source : un point de contact Grafana, une notification Uptime Kuma ou une tâche cron. Pour d'autres sources homelab, consultez les alertes homelab et le guide Proxmox. Pour d'autres intégrations, consultez les notifications webhook et les alertes Grafana. Si vous comparez les solutions, la page des alternatives détaille les différences.