# Surveillance de tâches cron avec Healthchecks.io : une notification push sur votre téléphone quand une tâche échoue ou ne se lance pas

> Surveillez vos tâches cron avec Healthchecks.io, hébergé ou auto-hébergé, et recevez une notification push sur votre téléphone quand une tâche échoue, bloque ou s’arrête sans prévenir. URL de ping avec /start et codes de sortie, options curl qui résistent à un mauvais réseau, runitor, et deux façons d’envoyer les alertes vers Pocket Alert. Plus un petit script enveloppe si vous ne voulez pas d’un service de plus.

*27.10.2026*

<!-- source: https://pocketalert.app/fr/blog/cron-job-monitoring-healthchecks -->

Une tâche cron peut tomber en panne de deux façons. Elle peut s’exécuter et échouer : `pg_dump` ne parvient pas à joindre la base de données, le disque est plein. Ou elle peut ne plus s’exécuter du tout : une ligne de crontab est supprimée, le serveur est reconstruit sans elle, le démon cron est arrêté. Le premier cas laisse une erreur quelque part. Le second ne laisse rien, et vous le découvrez le jour où vous avez besoin de la sauvegarde de la veille.

Une alerte qui attend que la tâche dise « j’ai échoué » n’entend jamais une tâche qui n’a pas démarré. Pour détecter ce cas, il faut le montage inverse : la tâche signale sa fin à chaque exécution, et quelque chose d’autre déclenche l’alarme quand ce signalement n’arrive pas.

Ce guide met cela en place avec [Healthchecks.io](https://healthchecks.io), le moniteur cron open source, et envoie ses alertes sur votre téléphone avec Pocket Alert. Les échecs arrivent en mode bruyant, les rétablissements en mode discret. Tout ce qui suit a été testé avec l’image Docker Healthchecks v5.0.3 auto-hébergée, et fonctionne de la même façon sur le service hébergé.

## Ce dont vous avez besoin

- Un compte Healthchecks sur healthchecks.io (l’offre gratuite Hobbyist surveille 20 tâches), ou votre propre instance à partir de l’image Docker `healthchecks/healthchecks`.
- L’application Pocket Alert sur votre [iPhone ou Android](/get-app) et une clé API issue de [Clés API](/account/apikeys). L’offre gratuite suffit pour commencer.
- `curl` sur la machine qui exécute les tâches cron.

## Le dead man's switch

Healthchecks appelle cela la surveillance par battement de cœur, une forme de dead man's switch. Chaque tâche obtient un **check** doté d’une URL de ping unique, que la tâche appelle à la fin de son exécution. Si la requête suivante n’arrive pas à temps, le check passe en **down** et les alertes partent.

Deux réglages déterminent « à temps » :

- **Période** : la fréquence à laquelle vous attendez un ping, toutes les heures, tous les jours.
- **Délai de tolérance** : le temps que Healthchecks attend après l’heure prévue avant de considérer le check comme down. Réglez-le plus long que la durée habituelle de la tâche, avec une marge.

Pour une tâche cron, choisissez plutôt le type de planification **Cron** et collez l’expression de votre crontab, ainsi que le fuseau horaire du serveur. Healthchecks attend alors des pings aux bons moments de la journée, et pas seulement à intervalles réguliers. L’[éditeur d’expressions cron](/tools/cron) détaille la signification d’une expression.

Lors de notre test, un check avec la planification `*/2 * * * *` et un délai de tolérance d’une minute a reçu un ping à 16:09:13. Rien n’a été reçu à 16:10, et le check est passé en down à 16:11:00, exactement une période de tolérance plus tard.

L’URL de ping existe en plusieurs variantes :

<div class="cmp-table-wrap">
<table class="cmp-table">
<thead><tr><th>Requête</th><th>Signification</th></tr></thead>
<tbody>
<tr><th><code>https://hc-ping.com/&lt;uuid&gt;</code></th><td>Succès. La tâche s’est terminée.</td></tr>
<tr><th><code>https://hc-ping.com/&lt;uuid&gt;/start</code></th><td>La tâche a démarré. Healthchecks attend désormais un succès dans le délai de tolérance et enregistre la durée d’exécution.</td></tr>
<tr><th><code>https://hc-ping.com/&lt;uuid&gt;/fail</code></th><td>La tâche a échoué. Le check passe immédiatement en down.</td></tr>
<tr><th><code>https://hc-ping.com/&lt;uuid&gt;/&lt;0-255&gt;</code></th><td>Un code de sortie. <code>0</code> compte comme un succès, toute autre valeur comme un échec.</td></tr>
</tbody>
</table>
</div>

Sur une instance auto-hébergée, la base est votre propre domaine suivi de `/ping/`, par exemple `https://hc.example.com/ping/<uuid>`.

## Brancher la tâche cron

Créez un check, copiez son URL de ping et modifiez la ligne de crontab. Nous avons testé cela avec le démon cron sur Debian 13 :

```bash
PING=https://hc-ping.com/your-check-uuid
15 3 * * * curl -fsS -m 10 --retry 5 -o /dev/null $PING/start; /usr/local/bin/backup.sh; curl -fsS -m 10 --retry 5 -o /dev/null $PING/$?
```

`PING=` est une variable de crontab, que le shell développe dans la commande. La ligne fait trois choses :

- Elle envoie `/start`, donc une tâche bloquée passe en down une fois le délai de tolérance écoulé. Lors de notre test, un `/start` sans suite a fait passer le check en down exactement une période de tolérance plus tard.
- Elle lance la tâche.
- Elle envoie `$?`, le code de sortie de la tâche. Une exécution réussie envoie `/0`, un échec envoie `/2` ou la valeur renvoyée par le script, et le check passe immédiatement en down.

Les options de curl évitent que le ping lui-même pose problème :

- **`-m 10`** limite chaque requête à 10 secondes. Un `/start` bloqué ne doit pas retenir la tâche.
- **`--retry 5`** relance les délais dépassés et les réponses 408, 429, 500, 502, 503 et 504, avec des délais croissants. Un paquet perdu ne doit pas vous réveiller.
- **`-fsS`** fait échouer curl sur les erreurs HTTP et reste silencieux tant que tout va bien, pour que cron ne vous envoie pas la barre de progression de curl par e-mail.
- **`-o /dev/null`** jette le corps de la réponse, qui se limite à `OK`.

Si la tâche est un pipeline comme `pg_dump | gzip > dump.gz`, son code de sortie est celui de `gzip`, et non celui de `pg_dump`. Placez-la dans un script avec `set -o pipefail` en bash, pour qu’un export échoué ne soit pas signalé comme réussi.

### Ou laissez runitor s’en charger

[runitor](https://github.com/bdd/runitor) est un petit binaire Go qui enveloppe une commande et gère les pings : `/start` avant, le code de sortie après, et les 10 000 derniers octets de la sortie de la commande joints au ping.

```bash
curl -fsSL -o /usr/local/bin/runitor https://github.com/bdd/runitor/releases/download/v1.4.1-build.6/runitor-v1.4.1-build.6-linux-amd64
chmod +x /usr/local/bin/runitor
```

La ligne de crontab devient plus courte :

```bash
15 3 * * * CHECK_UUID=your-check-uuid /usr/local/bin/runitor -- /usr/local/bin/backup.sh
```

Pour une instance auto-hébergée, ajoutez `HC_API_URL=https://hc.example.com/ping`. Nous avons utilisé runitor v1.4.1 de cette façon sous cron : une sauvegarde en échec a fait passer le check en down avec le code de sortie 2, et sa sortie d’erreur apparaissait dans l’alerte.

## Envoyer les alertes vers Pocket Alert

Healthchecks se connecte à Pocket Alert via son intégration générique **Webhook**. Rendez-vous dans **Intégrations**, trouvez **Webhook** et cliquez sur **Ajouter une intégration**. Le formulaire comporte deux sections, « Exécuter quand un check passe en down » et « Exécuter quand un check repasse en up », chacune avec sa propre URL, sa méthode, son corps et ses en-têtes. Cette séparation permet de rendre le « down » bruyant et le « up » discret.

Les deux sections acceptent des variables : `$NAME`, `$NAME_JSON`, `$STATUS`, `$NOW`, `$CODE`, `$SLUG`, `$TAGS`, `$EXITSTATUS`, `$BODY`, `$BODY_JSON`, `$JSON` et quelques autres. Pour les corps JSON, attention à la différence : `$NAME` est inséré tel quel, donc un check nommé `Nightly "db" backup` casse le JSON, alors que `$NAME_JSON` est une chaîne JSON complète, guillemets compris. Il en va de même pour `$BODY` et `$BODY_JSON`.

### Option 1 : directement vers l’API

Dans la section **down**, choisissez `POST` et l’URL `https://api.pocketalert.app/v1/messages`. En-têtes de requête, un par ligne :

```text
Content-Type: application/json
Token: YOUR_API_KEY
```

Corps de la requête :

```json
{
  "title": $NAME_JSON,
  "message": "DOWN since $NOW. Exit status of the last ping: $EXITSTATUS",
  "level": "high",
  "actions": [{"type": "view", "label": "Open check", "value": "https://healthchecks.io/checks/$CODE/details/"}]
}
```

Dans la section **up**, la même méthode, la même URL et les mêmes en-têtes, avec un corps plus discret :

```json
{
  "title": $NAME_JSON,
  "message": "Back up at $NOW",
  "level": "low"
}
```

Cliquez sur **Enregistrer l’intégration**. Une nouvelle intégration est rattachée à tous les checks existants du projet. Voici ce que Healthchecks a envoyé lorsque notre check de test a échoué :

```json
{
  "title": "Nightly \"db\" backup",
  "message": "DOWN since 2026-10-31T16:15:01+00:00. Exit status of the last ping: 2",
  "level": "high",
  "actions": [{"type": "view", "label": "Open check", "value": "https://healthchecks.io/checks/a4b72803-3a50-4b81-b33f-88dd2200ffc2/details/"}]
}
```

Quelques remarques sur ce corps :

- **`high` est prioritaire.** Il traverse Concentration et le récapitulatif programmé. Sur une offre payante, passez-le à `critical` : une sauvegarde morte vous réveille alors malgré le mode silencieux et Ne pas déranger. Sur l’offre gratuite, `critical` est accepté et livré comme `high`.
- **`low` pour les rétablissements.** « Sauvegarde de retour » arrive dans le fil sans son. Vous voulez le savoir, mais pas à 3 h du matin.
- **`$EXITSTATUS` distingue l’échec de l’absence.** C’est le code de sortie du dernier ping avant l’alerte. `2` signifie que la tâche s’est exécutée et a renvoyé 2. Un down avec `0` signifie que la dernière exécution a réussi et que la suivante n’a jamais eu lieu. `-1` signifie que le dernier ping ne portait aucun code de sortie : une simple URL de succès, `/fail` ou `/start`.
- **Le bouton** ouvre le check dans Healthchecks. Pour une instance auto-hébergée, mettez votre propre domaine dans l’URL. Les [boutons d’action](/features/action-buttons) sont une fonctionnalité payante : sur l’offre gratuite, ils sont retirés et le message est livré normalement.

### Option 2 : un webhook Pocket Alert avec un modèle

La seconde méthode envoie un petit document JSON à un webhook Pocket Alert, qui met en forme la notification push. Son avantage : elle peut inclure la sortie de la tâche.

Ouvrez [Webhooks](/webhooks) dans la console Pocket Alert, créez-en un nommé `Healthchecks` et définissez le modèle de message :

```text
%name% is %status% since %time%
%log%
```

Laissez **Priorité par défaut** non sélectionnée, car la charge utile porte son propre niveau. Copiez l’URL du webhook, qui ressemble à `https://p4a.me/wh/abc123xyz`. L’URL est un secret : traitez-la comme un mot de passe.

Dans Healthchecks, créez l’intégration webhook avec cette URL en `POST` dans les deux sections, l’en-tête `Content-Type: application/json` et les corps suivants. Down :

```json
{"name": $NAME_JSON, "status": "$STATUS", "time": "$NOW", "code": "$CODE", "log": $BODY_JSON, "level": "high"}
```

Up :

```json
{"name": $NAME_JSON, "status": "$STATUS", "time": "$NOW", "code": "$CODE", "log": $BODY_JSON, "level": "low"}
```

`$BODY_JSON` est le corps du dernier ping, c’est là que runitor place la sortie de la tâche. Lorsque la sauvegarde encapsulée par runitor a échoué lors de notre test, la notification affichait :

> **Webhook Healthchecks**
> DB backup (runitor) est down depuis 2026-10-31T16:15:02+00:00
> dumping appdb
> pg_dump: error: connection to server on socket failed: No such file or directory
>
> [runitor] exit status 2

Pocket Alert lit le champ `level` de premier niveau d’une charge utile entrante, donc `high` et `low` fonctionnent comme dans l’option 1. Sans runitor, `$BODY_JSON` est une chaîne vide et la deuxième ligne est vide. L’API ne peut pas faire cela : `$BODY_JSON` est une chaîne JSON complète, elle ne peut donc former que la totalité du `message`, et lorsque le ping n’avait pas de corps, ce message est vide et l’API le rejette.

Deux autres différences : le titre de la notification est toujours `Webhook <name>`, donc le nom du check passe dans le message, et les boutons de webhook se définissent via le champ `actions` de l’API webhooks, et non dans le formulaire de la console.

### Tester

Sur la page **Intégrations** de Healthchecks, chaque intégration possède un bouton **Test!**. Il envoie une notification « down » pour un check nommé `TEST`, qui arrive sous forme de notification push `high`. Lancez ensuite une tâche qui se termine avec le code `1` et observez l’arrivée de l’alerte réelle.

## Sans Healthchecks : un script enveloppe qui notifie en cas d’échec

Si vous ne voulez pas d’un service de plus, un petit script enveloppe couvre le cas le plus courant : une tâche qui se termine par une erreur. Enregistrez-le sous `/usr/local/bin/cron-alert` :

```bash
#!/bin/sh
# Usage: cron-alert <job name> <command> [args...]
name="$1"
shift

log=$(mktemp)
"$@" >"$log" 2>&1
status=$?

if [ "$status" -ne 0 ]; then
  curl -fsS -m 10 --retry 3 --retry-max-time 30 -o /dev/null \
    -H "Token: $POCKETALERT_API_KEY" \
    --form-string "title=Cron failed: $name on $(hostname)" \
    --form-string "message=Exit status $status. $(tail -c 2000 "$log")" \
    --form-string "level=high" \
    "${POCKETALERT_API_URL:-https://api.pocketalert.app/v1/messages}"
fi

cat "$log"
rm -f "$log"
exit "$status"
```

Et dans la crontab :

```bash
POCKETALERT_API_KEY=your-api-key
15 3 * * * /usr/local/bin/cron-alert "nightly backup" /usr/local/bin/backup.sh
```

Quelques choix délibérés :

- **`--form-string` au lieu du JSON.** L’API accepte les données de formulaire multipart, et `--form-string` envoie la sortie telle quelle, guillemets et retours à la ligne compris, sans `jq` ni échappement. Un simple `-F` traiterait une valeur commençant par `@` ou `<` comme un fichier.
- **`tail -c 2000`** conserve la fin de la sortie, où se trouve généralement l’erreur.
- **`--retry-max-time 30`** est important. Au-delà de la limite quotidienne de messages, l’API répond `429` avec un `Retry-After` correspondant au nombre de secondes jusqu’à minuit UTC, et l’option `--retry` de curl le respecte. Lors de notre test, sans cette option, curl attendait `Retry-After: 30000` jusqu’à ce que nous l’arrêtions. Avec elle, curl abandonne après une tentative.
- **Le script conserve le code de sortie et affiche la sortie**, donc les journaux cron et `MAILTO` fonctionnent comme avant.

Il passe shellcheck, et sous cron sur Debian 13, la sauvegarde en échec est arrivée sous la forme « Cron en échec : sauvegarde nocturne sur » suivi du nom d’hôte, avec l’erreur de `pg_dump` dans le texte.

Soyez clair sur ce que cela ne peut pas faire. Le script ne s’exécute que si cron l’exécute. Si la ligne de crontab est supprimée, si le démon est arrêté ou si la machine est éteinte, rien n’est envoyé : c’est l’échec silencieux du début de cet article. Une tâche qui se bloque indéfiniment passe aussi inaperçue. Pour ces cas, il faut quelque chose d’extérieur à la machine qui attend un battement de cœur, et c’est à cela que sert Healthchecks. La [CLI Pocket Alert](/tools/cli) peut remplacer l’appel `curl` si vous le préférez.

## Limites honnêtes

- **Healthchecks doit être en ligne pour détecter le problème.** Sur le service hébergé, c’est leur travail. Si vous l’auto-hébergez sur la même machine que les tâches cron, une machine morte emporte le moniteur avec elle. Hébergez-le ailleurs.
- **Le modèle de corps est limité à 1 000 caractères** dans Healthchecks. C’est largement suffisant pour les corps ci-dessus, mais pas pour un long message rédigé à la main.
- **Les longues sorties sont tronquées dans la notification push.** Elle contient environ les 3 premiers Ko du message ; le texte complet se trouve dans l’historique des messages de l’application.
- **Chaque alerte est un message.** Une tâche instable qui passe en down et en up toutes les quelques minutes envoie une notification à chaque fois, et sur les 50 messages par jour de l’offre gratuite, cela s’accumule. Corrigez la tâche ou augmentez le délai de tolérance.

## Si rien n’arrive

- **Utilisez d’abord le bouton Test!.** Si le test arrive mais pas les vraies alertes, vérifiez que l’intégration est activée pour ce check sur la page du check.
- **Consultez la page Intégrations de Healthchecks.** Une intégration en échec y est marquée **Failed** ; survolez-la pour voir la dernière erreur, par exemple `Received status code 401`. Un `401` signifie que l’en-tête `Token` est incorrect. Un `400` indique généralement que le corps n’est pas du JSON valide : vérifiez que vous avez utilisé `$NAME_JSON` sans guillemets autour, et non `"$NAME"`.
- **Un nouveau check n’alerte qu’après son premier ping.** Jusque-là, il est « new », pas « down ».
- **Vérifiez le fuseau horaire des checks cron.** Si un check est toujours en avance ou en retard d’une heure, le fuseau horaire du serveur ne correspond pas à celui défini sur le check.
- **Regardez dans le fil.** Les notifications `low` n’émettent aucun son : un rétablissement peut donc sembler ne jamais être arrivé.

## FAQ

### Dois-je utiliser l’API ou le webhook ?

La voie API place le nom du check dans le titre de la notification et ne nécessite rien de créer dans Pocket Alert. La voie webhook peut inclure la sortie de la tâche : avec runitor, privilégiez donc le webhook.

### Puis-je ne recevoir que les alertes « down » ?

Oui. Utilisez un corps `low` discret pour « up », comme ci-dessus, ou laissez l’URL « up » vide : Healthchecks n’envoie alors rien au rétablissement.

### Et les timers systemd ?

Même principe. Healthchecks propose un type de planification **OnCalendar** qui accepte les mêmes expressions que votre timer. Envoyez `/start` depuis `ExecStartPre`, ou encapsulez la commande `ExecStart` dans runitor.

### Où en savoir plus sur les alertes cron ?

La page [alertes de tâches cron](/use-cases/cron-job-alerts) explique comment envoyer une notification push depuis la tâche elle-même, [alertes de sauvegarde](/use-cases/backup-alerts) traite des outils de sauvegarde, et le [guide Proxmox](/blog/proxmox-alerts) couvre les sauvegardes sur un hyperviseur.

[Créez un compte gratuit](/signup), ajoutez une seule intégration webhook dans Healthchecks, et que la tâche qui a discrètement cessé de tourner soit celle qui vous réveille.
