# Monitoraggio cron job con Healthchecks.io: una notifica push sul telefono quando un job fallisce o non parte

> Monitora i cron job con Healthchecks.io, in cloud o self-hosted, e ricevi una notifica push sul telefono quando un job fallisce, si blocca o smette in silenzio di girare. URL di ping con /start e codici di uscita, flag curl che reggono una rete instabile, runitor e due modi per inviare gli avvisi a Pocket Alert. In più un piccolo wrapper, se non vuoi un altro servizio.

*27.10.2026*

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

Un cron job può rompersi in due modi. Può partire e fallire: `pg_dump` non riesce a raggiungere il database, il disco è pieno. Oppure può smettere del tutto di girare: una riga del crontab viene cancellata, il server viene ricostruito senza di essa, il demone cron è morto. Il primo tipo lascia un errore da qualche parte. Il secondo non lascia niente, e te ne accorgi il giorno in cui ti serve il backup di ieri sera.

Un sistema di alert che aspetta che il job dica "ho fallito" non sente mai un job che non è partito. Per intercettarlo serve il setup opposto: il job segnala la sua esecuzione ogni volta che termina, e qualcos'altro fa scattare l'allarme quando la segnalazione non arriva.

Questa guida costruisce proprio questo con [Healthchecks.io](https://healthchecks.io), il monitor open source per cron, e invia i suoi avvisi al telefono con Pocket Alert. I fallimenti arrivano in modo evidente, i ripristini in modo discreto. Tutto ciò che segue è stato testato con l'immagine Docker self-hosted di Healthchecks v5.0.3 e funziona allo stesso modo sul servizio cloud.

## Cosa ti serve

- Un account Healthchecks su healthchecks.io (il piano gratuito Hobbyist monitora 20 job), oppure una tua istanza dall'immagine Docker `healthchecks/healthchecks`.
- L'app Pocket Alert sul tuo [iPhone o Android](/get-app) e una chiave API da [Chiavi API](/account/apikeys). Il piano gratuito basta per iniziare.
- `curl` sulla macchina che esegue i cron job.

## Il dead man's switch

Healthchecks chiama questo meccanismo monitoraggio heartbeat, una sorta di dead man's switch. Ogni job ottiene un **check** con un URL di ping unico, che il job richiama quando termina. Se la richiesta successiva non arriva in tempo, il check passa a **down** e partono gli avvisi.

Due impostazioni decidono cosa significa "in tempo":

- **Period** è la frequenza con cui ti aspetti un ping: ogni ora, ogni giorno.
- **Grace time** è quanto Healthchecks aspetta oltre l'orario previsto prima di dichiarare il check down. Impostalo più lungo della durata abituale del job, più un margine.

Per un cron job, scegli invece il tipo di pianificazione **Cron** e incolla l'espressione dal crontab, insieme al fuso orario del server. Healthchecks si aspetta così i ping agli orari giusti della giornata, non solo a intervalli regolari. L'[editor di espressioni cron](/tools/cron) spiega il significato di ogni espressione.

Nel nostro test, un check con pianificazione `*/2 * * * *` e grace time di un minuto ha ricevuto un ping alle 16:09:13. Nessun ping alle 16:10, e il check è passato a down alle 16:11:00, esattamente un grace period dopo.

L'URL di ping ha alcune varianti:

<div class="cmp-table-wrap">
<table class="cmp-table">
<thead><tr><th>Richiesta</th><th>Significato</th></tr></thead>
<tbody>
<tr><th><code>https://hc-ping.com/&lt;uuid&gt;</code></th><td>Successo. Il job è terminato.</td></tr>
<tr><th><code>https://hc-ping.com/&lt;uuid&gt;/start</code></th><td>Il job è partito. Healthchecks ora si aspetta un successo entro il grace time e registra la durata dell'esecuzione.</td></tr>
<tr><th><code>https://hc-ping.com/&lt;uuid&gt;/fail</code></th><td>Il job è fallito. Il check passa subito a down.</td></tr>
<tr><th><code>https://hc-ping.com/&lt;uuid&gt;/&lt;0-255&gt;</code></th><td>Un codice di uscita. <code>0</code> conta come successo, qualsiasi altro valore come fallimento.</td></tr>
</tbody>
</table>
</div>

Su un'istanza self-hosted la base è il tuo dominio seguito da `/ping/`, per esempio `https://hc.example.com/ping/<uuid>`.

## Collega il cron job

Crea un check, copia il suo URL di ping e modifica la riga del crontab. Abbiamo eseguito tutto sotto il demone cron su 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=` è una variabile del crontab, che la shell espande nel comando. La riga fa tre cose:

- Invia `/start`, così un job bloccato passa a down allo scadere del grace time. Nel nostro test, un `/start` senza seguito ha portato il check a down esattamente un grace period dopo.
- Esegue il job.
- Invia `$?`, il codice di uscita del job. Un'esecuzione pulita invia `/0`, una fallita invia `/2` o qualunque valore abbia restituito lo script, e il check passa subito a down.

I flag di curl evitano che il ping crei problemi a sua volta:

- **`-m 10`** limita ogni richiesta a 10 secondi. Un `/start` bloccato non deve trattenere il job.
- **`--retry 5`** ritenta in caso di timeout e risposte 408, 429, 500, 502, 503 e 504, con ritardi crescenti. Un pacchetto perso non deve farti svegliare.
- **`-fsS`** fa fallire curl sugli errori HTTP e lo tiene silenzioso finché non succede qualcosa, così cron non ti spedisce per mail la barra di avanzamento di curl.
- **`-o /dev/null`** scarta il corpo della risposta, che è solo `OK`.

Se il job è una pipeline come `pg_dump | gzip > dump.gz`, il suo codice di uscita è quello di `gzip`, non di `pg_dump`. Spostala in uno script con `set -o pipefail` in bash, così un dump fallito non risulta come successo.

### Oppure lascia fare a runitor

[runitor](https://github.com/bdd/runitor) è un piccolo binario Go che avvolge un comando e gestisce i ping: `/start` prima, il codice di uscita dopo, e gli ultimi 10.000 byte dell'output del comando allegati al 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 riga del crontab diventa più corta:

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

Per un'istanza self-hosted aggiungi `HC_API_URL=https://hc.example.com/ping`. Abbiamo eseguito runitor v1.4.1 in questo modo sotto cron: un backup fallito ha portato il check a down con codice di uscita 2, e il suo output di errore è comparso nell'avviso.

## Invia gli avvisi a Pocket Alert

Healthchecks si collega a Pocket Alert tramite la sua integrazione generica **Webhook**. Vai su **Integrations**, trova **Webhook** e clicca **Add Integration**. Il form ha due sezioni, "Execute when a check goes down" ed "Execute when a check goes up", ognuna con il proprio URL, metodo, body e header. Questa separazione permette di rendere "down" evidente e "up" discreto.

Entrambe le sezioni accettano dei segnaposto: `$NAME`, `$NAME_JSON`, `$STATUS`, `$NOW`, `$CODE`, `$SLUG`, `$TAGS`, `$EXITSTATUS`, `$BODY`, `$BODY_JSON`, `$JSON` e alcuni altri. Per i body JSON fai attenzione alla differenza: `$NAME` viene incollato così com'è, quindi un check chiamato `Nightly "db" backup` rompe il JSON, mentre `$NAME_JSON` è una stringa JSON completa, virgolette incluse. Vale lo stesso per `$BODY` e `$BODY_JSON`.

### Opzione 1: direttamente all'API

Nella sezione **down** scegli `POST` e l'URL `https://api.pocketalert.app/v1/messages`. Header della richiesta, uno per riga:

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

Body della richiesta:

```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/"}]
}
```

Nella sezione **up** lo stesso metodo, URL e header, e un body più discreto:

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

Clicca **Save Integration**. Una nuova integrazione viene collegata a tutti i check esistenti del progetto. Questo è ciò che Healthchecks ha inviato quando il nostro check di test è fallito:

```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/"}]
}
```

Alcune note su questo body:

- **`high` è per ciò che è urgente.** Passa attraverso Full immersion e il riepilogo programmato. Con un piano a pagamento, cambialo in `critical` e un job di backup fermo ti sveglia anche con l'interruttore silenzioso e Non disturbare. Con il piano gratuito `critical` è accettato e consegnato come `high`.
- **`low` per i ripristini.** "Back up" arriva nel feed senza suono. Vuoi saperlo, ma non alle 3 di notte.
- **`$EXITSTATUS` distingue il fallimento dall'assenza.** È il codice di uscita dell'ultimo ping prima dell'avviso. `2` significa che il job è girato e ha restituito 2. Un down con `0` significa che l'ultima esecuzione è riuscita e quella successiva non è mai partita. `-1` significa che l'ultimo ping non aveva un codice di uscita: un semplice URL di successo, `/fail` o `/start`.
- **Il pulsante** apre il check in Healthchecks. Per un'istanza self-hosted, inserisci nell'URL il tuo dominio. I [pulsanti di azione](/features/action-buttons) sono una funzione a pagamento: nel piano gratuito vengono rimossi e il messaggio viene comunque consegnato normalmente.

### Opzione 2: un webhook Pocket Alert con un template

Il secondo modo invia un piccolo documento JSON a un webhook Pocket Alert, che formatta la notifica push. Il suo vantaggio: può includere l'output del job.

Apri [Webhooks](/webhooks) nella console di Pocket Alert, crea un webhook chiamato `Healthchecks` e imposta il template del messaggio:

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

Lascia **Default priority** non selezionata, perché il payload porta il proprio livello. Copia l'URL del webhook, che ha la forma `https://p4a.me/wh/abc123xyz`. L'URL è il segreto, quindi trattalo come una password.

In Healthchecks crea l'integrazione webhook con quell'URL come `POST` in entrambe le sezioni, l'header `Content-Type: application/json` e questi body. 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` è il body dell'ultimo ping, dove runitor inserisce l'output del job. Quando il backup avvolto da runitor è fallito nel nostro test, la notifica diceva:

> **Webhook Healthchecks**
> DB backup (runitor) is down since 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 legge il campo `level` di primo livello di un payload in arrivo, quindi `high` e `low` funzionano come nell'Opzione 1. Senza runitor, `$BODY_JSON` è una stringa vuota e la seconda riga resta bianca. L'API non può fare questo: `$BODY_JSON` è una stringa JSON completa, quindi può essere solo l'intero `message`, e quando il ping non aveva body quel messaggio è vuoto e l'API lo rifiuta.

Altre due differenze: il titolo della notifica è sempre `Webhook <name>`, quindi il nome del check va nel messaggio, e i pulsanti del webhook si impostano tramite il campo `actions` dell'API dei webhook, non dal form della console.

### Prova

Nella pagina **Integrations** di Healthchecks, ogni integrazione ha un pulsante **Test!**. Invia una notifica "down" per un check chiamato `TEST`, che arriva come notifica push `high`. Poi esegui un job che termina con `1` e osserva arrivare l'avviso reale.

## Senza Healthchecks: un wrapper che invia una push in caso di errore

Se non vuoi un altro servizio, un breve wrapper copre il caso più comune, cioè un job che termina con errore. Salvalo come `/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"
```

E nel crontab:

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

Alcune scelte deliberate:

- **`--form-string` invece di JSON.** L'API accetta dati multipart form, e `--form-string` invia l'output così com'è, virgolette e a capo inclusi, senza `jq` né escaping. Con `-F` puro, un valore che inizia con `@` o `<` verrebbe trattato come file.
- **`tail -c 2000`** mantiene la fine dell'output, dove di solito si trova l'errore.
- **`--retry-max-time 30`** è importante. Oltre il limite giornaliero di messaggi, l'API risponde `429` con un `Retry-After` pari ai secondi fino a mezzanotte UTC, e `--retry` di curl lo rispetta. Nel nostro test, senza questo flag curl restava in attesa di `Retry-After: 30000` finché non lo abbiamo interrotto. Con il flag, curl si arrende dopo un tentativo.
- **Il wrapper conserva il codice di uscita e stampa l'output**, quindi i log di cron e `MAILTO` continuano a funzionare come prima.

Passa shellcheck, e sotto cron su Debian 13 il backup fallito è arrivato come "Cron failed: nightly backup on" seguito dal nome host, con l'errore di `pg_dump` nel testo.

Sii chiaro su ciò che questo non può fare. Il wrapper gira solo quando cron lo esegue. Se la riga del crontab viene cancellata, il demone è giù o la macchina è spenta, non parte nulla: è il fallimento silenzioso da cui siamo partiti. Anche un job che si blocca per sempre passa inosservato. Per questi casi serve qualcosa fuori dalla macchina che aspetti un heartbeat, ed è a questo che serve Healthchecks. La [CLI di Pocket Alert](/tools/cli) può sostituire la chiamata `curl` se preferisci.

## Limiti onesti

- **Healthchecks deve essere raggiungibile per accorgersi di un problema.** Sul servizio cloud se ne occupa il fornitore. Se lo self-hosti sulla stessa macchina dei cron job, una macchina morta porta giù anche il monitor. Eseguilo altrove.
- **Il template del body è limitato a 1.000 caratteri** in Healthchecks. Sono abbastanza per i body qui sopra, ma non per un messaggio lungo scritto a mano.
- **L'output lungo viene tagliato nella push.** La push contiene circa i primi 3 KB del messaggio; il testo completo è nella cronologia dei messaggi nell'app.
- **Ogni avviso è un messaggio.** Un job instabile che va giù e su ogni pochi minuti invia una push ogni volta, e con i 50 messaggi al giorno del piano gratuito il conto sale in fretta. Correggi il job oppure aumenta il grace time.

## Se non arriva nulla

- **Usa prima il pulsante Test!.** Se il test arriva ma gli avvisi reali no, controlla che l'integrazione sia abilitata per quel check nella sua pagina.
- **Guarda la pagina Integrations di Healthchecks.** Un'integrazione in errore è segnata come **Failed**; passa sopra per vedere l'ultimo errore, per esempio `Received status code 401`. Un `401` significa che l'header `Token` è sbagliato. Un `400` di solito indica un body JSON non valido: verifica di aver usato `$NAME_JSON` senza virgolette attorno, e non `"$NAME"`.
- **Un check nuovo non avvisa fino al primo ping.** Fino ad allora è "new", non "down".
- **Controlla il fuso orario dei check cron.** Se un check è sempre un'ora in anticipo o in ritardo, il fuso orario del server non corrisponde a quello impostato nel check.
- **Controlla il feed.** Le push `low` non fanno suono, quindi un ripristino può sembrare mai arrivato.

## FAQ

### Devo usare la via API o la via webhook?

La via API mette il nome del check nel titolo della push e non richiede nulla da creare in Pocket Alert. La via webhook può includere l'output del job, quindi con runitor scegli il webhook.

### Posso ricevere solo gli avvisi "down"?

Sì. Usa un body `low` discreto per "up", come sopra, oppure lascia vuoto l'URL "up" e Healthchecks non invia nulla al ripristino.

### E i timer systemd?

Stessa idea. Healthchecks ha un tipo di pianificazione **OnCalendar** che accetta le stesse espressioni del tuo timer. Invia `/start` da `ExecStartPre`, oppure avvolgi il comando `ExecStart` con runitor.

### Dove posso leggere di più sugli avvisi cron?

La pagina [avvisi cron job](/use-cases/cron-job-alerts) spiega come inviare una push dal job stesso, [avvisi di backup](/use-cases/backup-alerts) copre gli strumenti di backup, e la [guida Proxmox](/blog/proxmox-alerts) tratta i backup su un hypervisor.

[Crea un account gratuito](/signup), aggiungi un'integrazione webhook in Healthchecks e lascia che sia il job che ha smesso in silenzio di girare a svegliarti.
