Retour au blog

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

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 :

  1. 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.
  2. Les notifications urgentes peuvent passer outre la Concentration. Dans Pocket Alert, les messages high arrivent comme urgents. Les niveaux inférieurs attendent la fin de la Concentration.
  3. 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 critical sur 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 faitPocket Alert fait
Détecte la panne et décide de son importanceReç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 JSONAssocie les champs, définit le niveau de priorité et livre à APNs
Envoie l'événement une seule fois, au moment où il se produitEnvoie à tous les appareils du compte, ou à l'appareil que vous indiquez
Conserve ses propres journauxConserve 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 refuse application/x-www-form-urlencoded, que curl -d envoie lorsque vous omettez l'en-tête. Utilisez -H "Content-Type: application/json" avec un corps JSON, ou -F pour des champs de formulaire.
  • title et message sont obligatoires. Tous les autres champs sont facultatifs.
  • Omettez device_id pour 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 :

NiveauValeurSur iPhoneUsage typique
silent-2Sans son, directement dans le Centre de notificationsÉvénements « résolus », journaux que vous pourrez lire plus tard
low-1Passive, n'allume pas l'écranInformatif
default0Notification normale avec sonRésultats courants, comme une sauvegarde terminée
high1Urgente, passe outre la ConcentrationDemande une attention rapide
critical2Alerte critique, sonne même en silencieuxDemande 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, ou critical pour 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

  1. 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.
  2. Testez avec la Concentration activée. Activez le mode Concentration que vous utilisez, envoyez un test high avec 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.
  3. 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.
  4. Consultez les journaux de votre source pour la requête sortante : URL, code de statut et corps de la réponse.
  5. 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 usage indique 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 :

  1. Créez un compte et installez l'application sur votre iPhone.
  2. Créez une clé API dans clés API.
  3. 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.

Partager cet article