Retour au blog

Notifications push Uptime Kuma sur votre téléphone : fortes quand un service tombe, discrètes au retour

Notifications push Uptime Kuma sur votre téléphone : fortes quand un service tombe, discrètes au retour

Uptime Kuma sait très bien repérer qu’un service est en panne. Reste à savoir où ce signal atterrit. La plupart des installations l’envoient dans un groupe Telegram, un canal Discord ou un dossier de messagerie, à côté de tout ce qui fait vibrer votre téléphone dans la journée. Et le message « de nouveau opérationnel » fait exactement le même bruit que celui de panne. Après quelques nuits d’instabilité, on finit par couper le canal et par ne plus le lire.

Ce guide envoie les alertes d’Uptime Kuma vers Pocket Alert sous forme de notifications push, avec des priorités différentes. Un moniteur qui tombe arrive en high, ce qui passe la Concentration sur iPhone. Un rétablissement arrive en low : il est dans le fil quand vous regardez, et il ne réveille personne. Tout repose sur le type de notification Webhook intégré à Uptime Kuma, il n’y a donc rien d’autre à installer.

Tout ce qui suit a été testé avec Uptime Kuma 2.5.8 exécuté dans Docker.

Ce dont vous avez besoin

  • Uptime Kuma 2.x. La plupart de ces étapes fonctionnent aussi avec la 1.23.x ; les différences sont indiquées à la fin.
  • L’application Pocket Alert sur votre téléphone et un compte. Créez un compte si vous n’en avez pas encore ; l’offre gratuite suffit pour commencer.
  • Une clé API depuis API Keys (méthode 1) ou une URL de webhook depuis Webhooks (méthode 2).

Deux façons de les connecter

La notification Webhook d’Uptime Kuma peut envoyer des requêtes vers n’importe quelle URL, avec son propre JSON ou un corps que vous écrivez. Cela donne deux méthodes :

Méthode 1 : API Pocket AlertMéthode 2 : URL de webhook Pocket Alert
URL d’envoihttps://api.pocketalert.app/v1/messageshttps://p4a.me/wh/<slug>
Titre de la notificationAu choix, par exemple Down: WebsiteToujours Webhook <name>
Panne bruyante, retour discretOuiOui, avec un corps personnalisé ; sinon un seul niveau pour tout
Secret conservé dans Uptime KumaUne clé API avec un accès complet à votre compteUne URL qui ne peut créer que des notifications push via ce webhook
Journal des requêtes dans Pocket AlertNonOui, dans l’historique des webhooks

Choisissez la méthode 1 si vous voulez des titres lisibles et le moins de pièces mobiles possible. Choisissez la méthode 2 si vous préférez ne pas stocker une clé API complète dans Uptime Kuma (il conserve les paramètres de notification, en-têtes compris, en JSON brut dans sa base de données), ou si vous voulez que chaque requête envoyée soit journalisée côté Pocket Alert pour le débogage.

Méthode 1 : envoyer directement à l’API Pocket Alert

Dans Uptime Kuma, ouvrez Settings → Notifications et cliquez sur Set Up Notification. Renseignez les champs ainsi :

  • Notification Type : Webhook
  • Friendly Name : Pocket Alert
  • Post URL : https://api.pocketalert.app/v1/messages
  • HTTP Method : POST
  • Request Body : Custom Body

Collez ceci dans le champ du corps, en remplaçant kuma.example.com par l’adresse de votre Uptime Kuma :

{%- assign level = "default" -%}
{%- assign title = "Uptime Kuma" -%}
{%- assign text = msg -%}
{%- if heartbeatJSON -%}
  {%- assign text = heartbeatJSON.msg | default: msg -%}
  {%- if heartbeatJSON.status == 0 -%}
    {%- assign title = "Down: " | append: monitorJSON.name -%}
    {%- assign level = "high" -%}
    {%- for tag in monitorJSON.tags -%}
      {%- if tag.name == "critical" -%}{%- assign level = "critical" -%}{%- endif -%}
    {%- endfor -%}
  {%- else -%}
    {%- assign title = "Up: " | append: monitorJSON.name -%}
    {%- assign level = "low" -%}
  {%- endif -%}
{%- elsif msg contains "will expire" -%}
  {%- assign title = "Expiring soon" -%}
{%- endif -%}
{
  "title": {{ title | json }},
  "message": {{ text | json }},
  "level": "{{ level }}",
  "actions": [
    {
      "type": "view",
      "label": "Open in Uptime Kuma",
      "value": "https://kuma.example.com/dashboard/{{ monitorJSON.id }}"
    }
  ]
}

Activez ensuite Additional Headers et collez :

{
  "Token": "YOUR_API_KEY",
  "Content-Type": "application/json"
}

Ce que fait le corps :

  • Le corps est un modèle Liquid. Uptime Kuma lui transmet msg (son texte prêt à l’emploi), monitorJSON (le moniteur) et heartbeatJSON (le contrôle qui a changé d’état). heartbeatJSON.status vaut 0 en cas de panne et 1 en cas de rétablissement.
  • | json produit une chaîne JSON complète, guillemets compris. Les messages d’erreur et les noms de moniteurs peuvent contenir des guillemets et des antislashs ; avec ce filtre, ils ne peuvent pas casser la requête. Un moniteur nommé Bob's "main" site produit toujours un JSON valide.
  • Panne en high, retour en low. high est traité comme urgent sur iPhone et passe la Concentration ainsi que le résumé programmé. low est livré sans vous interrompre.
  • Ajoutez le tag critical pour rendre une alerte plus forte. Ajoutez un tag nommé critical dans Uptime Kuma aux moniteurs les plus importants : leurs pannes sont envoyées en critical, ce qui sonne même avec le interrupteur silencieux et en mode Ne pas déranger. Les alertes critiques sont une fonctionnalité payante ; sur l’offre gratuite, elles sont livrées en high.
  • Les messages de certificat et de test n’ont pas de contrôle. Dans ce cas, la notification push utilise le texte d’Uptime Kuma comme message. Ce même texte sert de repli quand le message d’un contrôle est vide, comme pour un moniteur ping qui repasse en ligne ; l’API rejette une notification push au message vide.
  • Le bouton ouvre le moniteur. /dashboard/<id> est la page du moniteur dans Uptime Kuma. Pour un avertissement de certificat, il n’y a pas d’identifiant de moniteur : le bouton ouvre alors le tableau de bord. Les boutons d’action sont une fonctionnalité payante ; sur l’offre gratuite, l’API les supprime et la notification push est livrée sans bouton. Voir boutons d’action pour ce qu’ils permettent d’autre.

Ne sautez pas l’en-tête Content-Type. Quand Uptime Kuma envoie un corps personnalisé, il l’étiquette application/x-www-form-urlencoded si vous ne précisez rien. C’est ce qu’il a envoyé lors de mon test. L’API Pocket Alert n’accepte que le JSON ou le multipart, et répond à cette requête par un 400.

Cliquez sur Test. Une notification intitulée « Uptime Kuma » avec le texte « Pocket Alert Testing » doit arriver en quelques secondes. Enregistrez.

Voici ce qu’une vraie panne puis un vrai rétablissement ont envoyé depuis Uptime Kuma 2.5.8 :

{
  "title": "Down: Website",
  "message": "timeout of 4000ms exceeded",
  "level": "high",
  "actions": [
    { "type": "view", "label": "Open in Uptime Kuma", "value": "https://kuma.example.com/dashboard/1" }
  ]
}
{
  "title": "Up: Website",
  "message": "200 - OK",
  "level": "low",
  "actions": [
    { "type": "view", "label": "Open in Uptime Kuma", "value": "https://kuma.example.com/dashboard/1" }
  ]
}

Utilisez une clé API distincte, nommée d’après Uptime Kuma, pour pouvoir la révoquer seule si ce serveur est un jour compromis.

Méthode 2 : une URL de webhook Pocket Alert

Ici, Uptime Kuma envoie son propre JSON vers un webhook Pocket Alert, et un modèle côté Pocket Alert le transforme en notification push.

Créer le webhook

Le modèle du bouton ne peut être défini que via l’API ; le plus rapide est donc un seul appel. Il crée un webhook nommé « Uptime Kuma » avec un modèle de message, un niveau par défaut high (1) et un bouton « Open in Uptime Kuma », puis affiche l’URL de réception :

PA_KEY='your-api-key'
KUMA_URL='https://kuma.example.com'

jq -n --arg kuma "$KUMA_URL" '{
  name: "Uptime Kuma",
  message: "%msg%",
  default_level: 1,
  actions: ([{type: "view", label: "Open in Uptime Kuma", value: ($kuma + "/dashboard/%monitor.id%")}] | tojson)
}' |
curl -sS https://api.pocketalert.app/v1/webhooks \
  -H "Token: $PA_KEY" \
  -H 'Content-Type: application/json' \
  --data-binary @- |
jq -r '"Receive URL: https://p4a.me/wh/" + .url'

Si vous préférez cliquer, créez-le dans la console, sur Webhooks : nom Uptime Kuma, Default priority High, message %msg%. Vous obtiendrez les mêmes notifications push, sans le bouton.

Configurer Uptime Kuma

Créez une nouvelle notification de type Webhook, collez l’URL de réception comme Post URL, et réglez Request Body sur Preset - application/json. Aucun en-tête n’est nécessaire : l’URL fait office de secret, traitez-la comme un mot de passe. Ne choisissez pas le préréglage multipart ; les webhooks Pocket Alert ne lisent que le JSON.

Voici ce qu’Uptime Kuma a envoyé lors de mon test, au moment où un moniteur est tombé (raccourci ; l’objet monitor compte une centaine de champs) :

{
  "heartbeat": {
    "monitorID": 1,
    "status": 0,
    "time": "2026-10-31 16:09:56.331",
    "msg": "timeout of 4000ms exceeded",
    "important": true,
    "localDateTime": "2026-10-31 16:09:56"
  },
  "monitor": {
    "id": 1,
    "name": "Website",
    "url": "http://tls-target/",
    "type": "http",
    "tags": []
  },
  "msg": "[Website] [🔴 Down] timeout of 4000ms exceeded"
}

Le modèle %msg% utilise le msg de premier niveau, car c’est le seul champ présent dans chaque requête. Pour les avertissements de certificat et les messages de test, heartbeat et monitor valent null et seul msg est renseigné. La notification push arrive avec le titre « Webhook Uptime Kuma » et le texte « [Website] [🔴 Down] timeout of 4000ms exceeded ». Un emplacement dont le chemin est absent est remplacé par une chaîne vide ; ainsi, sur un avertissement de certificat, le bouton pointe vers /dashboard/ et fonctionne tout de même.

Panne bruyante, retour discret avec cette méthode

Avec le préréglage JSON, chaque requête reçoit le niveau par défaut du webhook : les rétablissements arrivent donc aussi fort que les pannes. Pour corriger cela, passez Request Body sur Custom Body et envoyez vous-même un champ level. Les webhooks Pocket Alert lisent un level de premier niveau dans la charge utile avant de revenir au niveau par défaut :

{
  "level": "{% if heartbeatJSON %}{% if heartbeatJSON.status == 0 %}high{% else %}low{% endif %}{% else %}default{% endif %}",
  "msg": {{ msg | json }},
  "monitor": { "id": "{{ monitorJSON.id }}" }
}

Le corps conserve les noms de champs msg et monitor.id, donc les modèles de message et de bouton du webhook fonctionnent sans modification. Les webhooks Pocket Alert lisent le corps en JSON quel que soit son Content-Type, cette méthode n’a donc besoin d’aucun en-tête supplémentaire.

Activer la notification pour chaque moniteur

Une notification ne fait rien tant qu’un moniteur ne l’utilise pas. En bas du formulaire de notification, il y a deux interrupteurs :

  • Default enabled active cette notification sur chaque moniteur que vous créerez à partir de maintenant.
  • Apply on all existing monitors l’ajoute à tous les moniteurs déjà existants. Cette action s’exécute une seule fois à l’enregistrement et n’est pas mémorisée.

Activez les deux lors du premier enregistrement. Pour exclure un moniteur, ouvrez-le et décochez la notification dans son formulaire de modification.

Avertissements d’expiration des certificats

Uptime Kuma peut vous prévenir avant qu’un certificat TLS n’expire. Ouvrez un moniteur HTTP(s) (les moniteurs Keyword et JSON Query le proposent aussi) et cochez Certificate Expiry Notification sous Advanced. La case est grisée tant que Ignore TLS/SSL errors for HTTPS websites est activé.

Les seuils sont globaux, sous Settings → Notifications → TLS Certificate Expiry, et valent par défaut 7, 14 et 21 jours. L’avertissement part vers les mêmes notifications que les pannes du moniteur, avec un texte de ce type :

[TLS site][https://tls-target/] server certificate tls-target will expire in 4 days

Le corps de la méthode 1 le repère avec msg contains "will expire" et l’intitule « Expiring soon » au niveau default. Uptime Kuma ne l’envoie qu’une fois par seuil, et non à chaque contrôle : lors de mon test, le moniteur a été contrôlé 119 fois avec un certificat expirant dans quatre jours, et un seul avertissement est parti.

Empêcher un moniteur instable de saturer votre téléphone

Trois paramètres du moniteur déterminent le niveau de bruit que produit un service instable :

ParamètreCe qu’il faitValeur conseillée
RetriesNombre de contrôles échoués marqués Pending avant que le moniteur ne soit considéré comme en panne. Les contrôles en attente n’envoient aucune notification.2 ou 3
Heartbeat Retry IntervalSecondes entre deux contrôles pendant l’attente.20 à 60
Resend Notification if Down X times consecutivelyRépète l’alerte de panne après ce nombre de contrôles échoués supplémentaires. 0 ne l’envoie qu’une fois.0, ou une valeur qui correspond à 30 à 60 minutes

Avec Retries réglé sur 2 lors de mon test, les deux premiers contrôles échoués ont été marqués en attente, et seul le troisième a envoyé « Down ». Avec Resend réglé sur 3, l’alerte de panne a été répétée après chaque groupe de trois contrôles échoués supplémentaires, jusqu’au retour du service. Le nombre de renvois se compte en contrôles, et non en minutes. Avec un intervalle de 60 secondes, 30 signifie un rappel toutes les demi-heures.

Chaque panne, chaque rétablissement et chaque renvoi représente un message. L’offre gratuite en autorise 50 par jour : un seul moniteur instable sans nouvelles tentatives peut donc tout consommer en un après-midi. Les nouvelles tentatives sont la solution la plus simple.

Si rien n’arrive

  • Le test échoue avec HTTP 400. Sur la méthode 1, vérifiez que Additional Headers contient "Content-Type": "application/json". Sans cela, la requête part en données de formulaire.
  • HTTP 401. L’en-tête Token est absent ou la clé a été révoquée. Créez-en une nouvelle depuis API Keys.
  • Le test arrive mais les pannes non. Ouvrez le moniteur et vérifiez que la notification est cochée. Par ailleurs, Uptime Kuma n’envoie pas de notification lors du premier contrôle d’un moniteur qui est en ligne ; un nouveau moniteur reste donc silencieux tant que rien ne change.
  • La méthode 2 n’affiche rien. Ouvrez l’historique du webhook dans la console. Si la requête y figure avec une erreur, celle-ci indique la cause : JSON invalide, ou modèle qui a produit un message vide. Si rien n’est enregistré du tout, Uptime Kuma n’a jamais atteint p4a.me. Vous pouvez aussi envoyer des requêtes vers le testeur de webhook pour voir exactement ce qu’Uptime Kuma envoie.
  • Un rétablissement semble manquer. Les notifications low sont silencieuses. Consultez le fil dans l’application.

FAQ

Quelle version d’Uptime Kuma faut-il ?

Le guide a été testé avec la 2.5.8, la dernière version au moment de l’écriture. La version 1.23.x dispose aussi du type Webhook avec Custom Body et Additional Headers, et son modèle reçoit les mêmes variables msg, monitorJSON et heartbeatJSON. J’ai rendu le corps de la méthode 1 avec le moteur de modèles livré dans la 1.23.16 et obtenu le même JSON, mais le test complet de bout en bout n’a été réalisé que sur la 2.5.8.

Que se passe-t-il si le serveur qui fait tourner Uptime Kuma tombe ?

Alors plus rien n’envoie l’alerte. Uptime Kuma ne peut pas signaler sa propre panne : faites surveiller son serveur par quelque chose d’extérieur, comme un contrôle depuis une autre machine ou un service de supervision hébergé. La page surveillance de disponibilité répertorie les services hébergés compatibles avec les webhooks Pocket Alert.

Puis-je envoyer des moniteurs différents vers des téléphones différents ?

Oui, avec une offre payante. Créez une notification par groupe avec un device_id différent dans le corps (méthode 1), ou un webhook distinct avec son propre appareil (méthode 2), puis cochez la bonne sur chaque moniteur. L’offre gratuite n’inclut qu’un appareil et un webhook, donc un seul téléphone destinataire.

Cela fonctionne-t-il pour les moniteurs ping, port et DNS ?

Oui. Le corps n’utilise que le nom et l’identifiant du moniteur, ainsi que le statut et le message du contrôle, que tous les types de moniteurs possèdent. Certains types, le ping notamment, laissent le message vide quand le contrôle réussit ; le corps se rabat alors sur le texte d’Uptime Kuma. Le bouton renvoie vers la page du moniteur dans Uptime Kuma et non vers l’adresse contrôlée, il fonctionne donc même quand cette adresse n’est pas une URL.

J’utilise déjà tout cela pour Proxmox. Puis-je partager une clé API ?

Oui, mais donnez à Uptime Kuma sa propre clé afin que révoquer l’une ne casse pas l’autre. Le guide Proxmox couvre les alertes de sauvegarde et de disque pour le même homelab.

Créez un compte gratuit, collez le corps dans une notification Webhook, et laissez la prochaine panne atteindre votre téléphone pendant que le rétablissement attend discrètement dans le fil.

Partager cet article