# Monitorización de cron jobs con Healthchecks.io: una notificación push en tu teléfono cuando una tarea falla o no se ejecuta

> Monitoriza tus cron jobs con Healthchecks.io, alojado o autoalojado, y recibe una notificación push en el teléfono cuando una tarea falla, se bloquea o deja de ejecutarse en silencio. URLs de ping con /start y códigos de salida, flags de curl que sobreviven a una mala red, runitor y dos formas de enviar alertas a Pocket Alert. Además, un pequeño wrapper para cuando no quieres otro servicio.

*27.10.2026*

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

Un cron job puede fallar de dos maneras. Puede ejecutarse y fallar: `pg_dump` no puede conectarse a la base de datos o el disco está lleno. O puede dejar de ejecutarse por completo: se borra una línea del crontab, el servidor se reconstruye sin ella o el demonio cron ha muerto. El primer caso deja un error en algún sitio. El segundo no deja nada, y te enteras el día que necesitas la copia de seguridad de anoche.

Una alerta que espera a que el job diga "he fallado" nunca oye hablar de un job que no arrancó. Para detectarlo necesitas la configuración opuesta: el job informa cada vez que termina, y otra cosa dispara la alarma cuando ese informe no llega.

Esta guía lo construye con [Healthchecks.io](https://healthchecks.io), el monitor de cron de código abierto, y envía sus alertas a tu teléfono con Pocket Alert. Los fallos llegan con fuerza, las recuperaciones llegan discretamente. Todo lo que aparece abajo se probó con la imagen Docker de Healthchecks v5.0.3 autoalojada, y funciona igual en el servicio alojado.

## Lo que necesitas

- Una cuenta de Healthchecks en healthchecks.io (el plan gratuito Hobbyist monitoriza 20 jobs), o tu propia instancia a partir de la imagen Docker `healthchecks/healthchecks`.
- La aplicación Pocket Alert en tu [iPhone o Android](/get-app) y una clave de API de [Claves de API](/account/apikeys). El plan gratuito basta para empezar.
- `curl` en la máquina que ejecuta los cron jobs.

## El interruptor de hombre muerto

Healthchecks llama a esto monitorización por heartbeat, una especie de interruptor de hombre muerto. Cada job obtiene un **check** con una URL de ping única que el job solicita al terminar. Si la siguiente solicitud no llega a tiempo, el check pasa a **down** y se envían alertas.

Dos ajustes deciden qué significa "a tiempo":

- **Periodo** es con qué frecuencia esperas un ping: cada hora, cada día.
- **Tiempo de gracia** es cuánto espera Healthchecks después del momento previsto antes de dar el check por caído. Ponlo más largo que lo que el job suele tardar, con un margen extra.

Para un cron job, elige en su lugar el tipo de programación **Cron** y pega la expresión de tu crontab, junto con la zona horaria del servidor. Healthchecks entonces espera pings a las horas correctas del día, no solo a intervalos correctos. El [editor de expresiones cron](/tools/cron) explica qué significa cada expresión.

En nuestra prueba, un check con la programación `*/2 * * * *` y un tiempo de gracia de un minuto recibió un ping a las 16:09:13. Nada le hizo ping a las 16:10, y el check pasó a down a las 16:11:00, exactamente un periodo de gracia después.

La URL de ping tiene algunas variantes:

<div class="cmp-table-wrap">
<table class="cmp-table">
<thead><tr><th>Solicitud</th><th>Significado</th></tr></thead>
<tbody>
<tr><th><code>https://hc-ping.com/&lt;uuid&gt;</code></th><td>Éxito. El job terminó.</td></tr>
<tr><th><code>https://hc-ping.com/&lt;uuid&gt;/start</code></th><td>El job ha arrancado. Healthchecks ahora espera un éxito dentro del tiempo de gracia y registra la duración de la ejecución.</td></tr>
<tr><th><code>https://hc-ping.com/&lt;uuid&gt;/fail</code></th><td>El job ha fallado. El check pasa a down de inmediato.</td></tr>
<tr><th><code>https://hc-ping.com/&lt;uuid&gt;/&lt;0-255&gt;</code></th><td>Un código de salida. <code>0</code> cuenta como éxito, cualquier otro valor como fallo.</td></tr>
</tbody>
</table>
</div>

En una instancia autoalojada, la base es tu propio dominio más `/ping/`, por ejemplo `https://hc.example.com/ping/<uuid>`.

## Conecta el cron job

Crea un check, copia su URL de ping y modifica la línea del crontab. Lo probamos con el demonio cron en 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=` es una variable del crontab, que la shell expande en el comando. La línea hace tres cosas:

- Envía `/start`, así que un job bloqueado pasa a down cuando se agota el tiempo de gracia. En nuestra prueba, un `/start` sin seguimiento hizo que el check pasara a down exactamente un periodo de gracia después.
- Ejecuta el job.
- Envía `$?`, el código de salida del job. Una ejecución correcta envía `/0`, una fallida envía `/2` o lo que devolviera el script, y el check pasa a down de inmediato.

Los flags de curl evitan que el ping cause problemas propios:

- **`-m 10`** limita cada solicitud a 10 segundos. Un `/start` bloqueado no debe retener el job.
- **`--retry 5`** reintenta los timeouts y las respuestas 408, 429, 500, 502, 503 y 504, con retrasos crecientes. Un paquete perdido no debería avisarte.
- **`-fsS`** hace que curl falle ante errores HTTP y permanezca en silencio salvo que algo vaya mal, así cron no te envía por correo la barra de progreso de curl.
- **`-o /dev/null`** descarta el cuerpo de la respuesta, que es solo `OK`.

Si el job es un pipeline como `pg_dump | gzip > dump.gz`, su código de salida es el de `gzip`, no el de `pg_dump`. Muévelo a un script con `set -o pipefail` en bash, para que un volcado fallido no informe de éxito.

### O deja que runitor lo haga

[runitor](https://github.com/bdd/runitor) es un pequeño binario en Go que envuelve un comando y gestiona los pings: `/start` antes, el código de salida después, y los últimos 10.000 bytes de la salida del comando adjuntos 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 línea del crontab queda más corta:

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

Para una instancia autoalojada, añade `HC_API_URL=https://hc.example.com/ping`. Ejecutamos runitor v1.4.1 de esta forma bajo cron: una copia de seguridad fallida hizo que el check pasara a down con código de salida 2, y su salida de error llegó en la alerta.

## Envía alertas a Pocket Alert

Healthchecks se conecta con Pocket Alert a través de su integración genérica **Webhook**. Ve a **Integraciones**, busca **Webhook** y haz clic en **Añadir integración**. El formulario tiene dos secciones, "Ejecutar cuando un check pase a down" y "Ejecutar cuando un check pase a up", cada una con su propia URL, método, cuerpo y cabeceras. Esa división permite que "down" sea ruidoso y "up" silencioso.

Ambas secciones aceptan marcadores: `$NAME`, `$NAME_JSON`, `$STATUS`, `$NOW`, `$CODE`, `$SLUG`, `$TAGS`, `$EXITSTATUS`, `$BODY`, `$BODY_JSON`, `$JSON` y algunos más. En cuerpos JSON, ten en cuenta la diferencia: `$NAME` se pega tal cual, así que un check llamado `Nightly "db" backup` rompe el JSON, mientras que `$NAME_JSON` es una cadena JSON completa, con comillas incluidas. Lo mismo ocurre con `$BODY` y `$BODY_JSON`.

### Opción 1: directamente a la API

En la sección **down**, elige `POST` y la URL `https://api.pocketalert.app/v1/messages`. Cabeceras de la solicitud, una por línea:

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

Cuerpo de la solicitud:

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

En la sección **up**, el mismo método, URL y cabeceras, y un cuerpo más discreto:

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

Haz clic en **Guardar integración**. Una nueva integración se adjunta a todos los checks existentes del proyecto. Esto es lo que envió Healthchecks cuando falló nuestro check de prueba:

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

Algunas notas sobre este cuerpo:

- **`high` es urgente.** Atraviesa Concentración y el resumen programado. En un plan de pago, cámbialo a `critical` y una copia de seguridad caída te despertará saltándose el modo silencio y No molestar. En el plan gratuito, `critical` se acepta y se entrega como `high`.
- **`low` para las recuperaciones.** "Back up" aparece en el feed sin sonido. Quieres saberlo, pero no a las 3 de la madrugada.
- **`$EXITSTATUS` distingue un fallo de una ausencia.** Es el código de salida del último ping antes de la alerta. `2` significa que el job se ejecutó y devolvió 2. Un down con `0` significa que la última ejecución tuvo éxito y la siguiente nunca llegó. `-1` significa que el último ping no traía código de salida: una URL de éxito simple, `/fail` o `/start`.
- **El botón** abre el check en Healthchecks. En una instancia autoalojada, pon tu propio dominio en la URL. Los [botones de acción](/features/action-buttons) son una función de pago; en el plan gratuito se eliminan y el mensaje se entrega igualmente.

### Opción 2: un webhook de Pocket Alert con plantilla

La segunda forma envía un pequeño documento JSON a un webhook de Pocket Alert, que da formato a la notificación push. Su ventaja: puede incluir la salida del job.

Abre [Webhooks](/webhooks) en la consola de Pocket Alert, crea uno llamado `Healthchecks` y define la plantilla del mensaje:

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

Deja **Prioridad predeterminada** sin seleccionar, porque el payload incluye su propio nivel. Copia la URL del webhook, que tiene el aspecto de `https://p4a.me/wh/abc123xyz`. La URL es el secreto, así que trátala como una contraseña.

En Healthchecks, crea la integración de webhook con esa URL como `POST` en ambas secciones, la cabecera `Content-Type: application/json` y estos cuerpos. 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` es el cuerpo del último ping, que es donde runitor deja la salida del job. Cuando la copia de seguridad envuelta con runitor falló en nuestra prueba, la notificación push decía:

> **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 lee el campo `level` de primer nivel de un payload entrante, así que `high` y `low` funcionan como en la opción 1. Sin runitor, `$BODY_JSON` es una cadena vacía y la segunda línea queda en blanco. La API no puede hacer esto: `$BODY_JSON` es una cadena JSON completa, así que solo puede ser el `message` entero, y cuando el ping no tenía cuerpo ese mensaje está vacío y la API lo rechaza.

Otras dos diferencias: el título de la notificación push siempre es `Webhook <name>`, así que el nombre del check va en el mensaje, y los botones de los webhooks se configuran mediante el campo `actions` de la API de webhooks, no desde el formulario de la consola.

### Pruébalo

En la página **Integraciones** de Healthchecks, cada integración tiene un botón **Test!**. Envía una notificación "down" para un check llamado `TEST`, que llega como una push `high`. Después ejecuta un job que termine con `1` y observa cómo llega la alerta real.

## Sin Healthchecks: un wrapper que envía una push al fallar

Si no quieres otro servicio, un pequeño wrapper cubre el caso más común: un job que termina con un error. Guárdalo como `/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"
```

Y en el crontab:

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

Algunas decisiones deliberadas:

- **`--form-string` en lugar de JSON.** La API acepta datos de formulario multipart, y `--form-string` envía la salida tal cual, con comillas y saltos de línea, sin `jq` ni escapado. Con `-F` normal, un valor que empiece por `@` o `<` se trataría como un archivo.
- **`tail -c 2000`** conserva el final de la salida, donde suele estar el error.
- **`--retry-max-time 30`** es importante. Si se supera el límite diario de mensajes, la API responde `429` con un `Retry-After` con los segundos hasta medianoche UTC, y el `--retry` de curl lo respeta. En nuestra prueba, sin este flag curl esperó `Retry-After: 30000` hasta que lo matamos. Con él, curl se rinde tras un intento.
- **El wrapper conserva el código de salida y muestra la salida**, así que los logs de cron y `MAILTO` siguen funcionando como antes.

Pasa shellcheck, y bajo cron en Debian 13 la copia de seguridad fallida llegó como "Cron failed: nightly backup on" más el nombre del host, con el error de `pg_dump` en el texto.

Sé claro sobre lo que no puede hacer. El wrapper solo se ejecuta cuando cron lo ejecuta. Si se borra la línea del crontab, el demonio está caído o la máquina está apagada, no se envía nada: es el fallo silencioso con el que empezaba este artículo. Un job que se bloquea para siempre también pasa desapercibido. Para esos casos necesitas algo fuera de la máquina esperando un heartbeat, que es para lo que sirve Healthchecks. La [CLI de Pocket Alert](/tools/cli) puede sustituir la llamada a `curl` si lo prefieres.

## Límites reales

- **Healthchecks tiene que estar en marcha para notarlo.** En el servicio alojado, eso es responsabilidad de ellos. Si lo autoalojas en la misma máquina que los cron jobs, una máquina caída se lleva también al monitor. Ejecútalo en otro sitio.
- **La plantilla del cuerpo está limitada a 1.000 caracteres** en Healthchecks. Basta para los cuerpos de arriba, pero no para un mensaje largo escrito a mano.
- **La salida larga se corta en la push.** La push incluye aproximadamente los primeros 3 KB del mensaje; el texto completo está en el historial de mensajes de la aplicación.
- **Cada alerta es un mensaje.** Un job inestable que pasa a down y a up cada pocos minutos envía una push cada vez, y en el plan gratuito, con 50 mensajes al día, eso se acumula. Arregla el job o aumenta el tiempo de gracia.

## Si no llega nada

- **Usa primero el botón Test!.** Si la prueba llega pero las alertas reales no, comprueba que la integración esté habilitada para ese check en la página del check.
- **Revisa la página Integraciones en Healthchecks.** Una integración que falla aparece marcada como **Failed**; pasa el cursor sobre ella para ver el último error, como `Received status code 401`. Un `401` significa que la cabecera `Token` es incorrecta. Un `400` suele indicar que el cuerpo no es JSON válido: comprueba que usaste `$NAME_JSON` sin comillas alrededor, y no `"$NAME"`.
- **Un check nuevo no avisa hasta su primer ping.** Hasta entonces está "new", no "down".
- **Comprueba la zona horaria de los checks cron.** Si un check siempre llega una hora antes o después, la zona horaria del servidor no coincide con la del check.
- **Mira en el feed.** Las push `low` no hacen ruido, así que una recuperación puede parecer que nunca llegó.

## Preguntas frecuentes

### ¿Debo usar la vía de la API o la del webhook?

La vía de la API pone el nombre del check en el título de la push y no necesita crear nada en Pocket Alert. La vía del webhook puede incluir la salida del job, así que con runitor, usa el webhook.

### ¿Puedo recibir solo las alertas de "down"?

Sí. Usa un cuerpo `low` silencioso para "up", como arriba, o deja vacía la URL de "up" y Healthchecks no enviará nada al recuperarse.

### ¿Qué pasa con los timers de systemd?

La idea es la misma. Healthchecks tiene un tipo de programación **OnCalendar** que acepta las mismas expresiones que tu timer. Envía `/start` desde `ExecStartPre`, o envuelve el comando de `ExecStart` con runitor.

### ¿Dónde puedo leer más sobre alertas de cron?

La página de [alertas de cron jobs](/use-cases/cron-job-alerts) explica cómo enviar una push desde el propio job, [alertas de copias de seguridad](/use-cases/backup-alerts) cubre las herramientas de backup, y la [guía de Proxmox](/blog/proxmox-alerts) trata las copias de seguridad en un hipervisor.

[Crea una cuenta gratuita](/signup), añade una integración de webhook en Healthchecks y deja que el job que dejó de ejecutarse en silencio sea el que te despierte.
