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

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, 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 y una clave de API de Claves de API. El plan gratuito basta para empezar.
curlen 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 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:
| Solicitud | Significado |
|---|---|
https://hc-ping.com/<uuid> | Éxito. El job terminó. |
https://hc-ping.com/<uuid>/start | El job ha arrancado. Healthchecks ahora espera un éxito dentro del tiempo de gracia y registra la duración de la ejecución. |
https://hc-ping.com/<uuid>/fail | El job ha fallado. El check pasa a down de inmediato. |
https://hc-ping.com/<uuid>/<0-255> | Un código de salida. 0 cuenta como éxito, cualquier otro valor como fallo. |
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:
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/startsin 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/2o 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 10limita cada solicitud a 10 segundos. Un/startbloqueado no debe retener el job.--retry 5reintenta los timeouts y las respuestas 408, 429, 500, 502, 503 y 504, con retrasos crecientes. Un paquete perdido no debería avisarte.-fsShace 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/nulldescarta el cuerpo de la respuesta, que es soloOK.
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 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.
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:
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:
Content-Type: application/json
Token: YOUR_API_KEY
Cuerpo de la solicitud:
{
"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:
{
"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:
{
"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:
highes urgente. Atraviesa Concentración y el resumen programado. En un plan de pago, cámbialo acriticaly una copia de seguridad caída te despertará saltándose el modo silencio y No molestar. En el plan gratuito,criticalse acepta y se entrega comohigh.lowpara las recuperaciones. "Back up" aparece en el feed sin sonido. Quieres saberlo, pero no a las 3 de la madrugada.$EXITSTATUSdistingue un fallo de una ausencia. Es el código de salida del último ping antes de la alerta.2significa que el job se ejecutó y devolvió 2. Un down con0significa que la última ejecución tuvo éxito y la siguiente nunca llegó.-1significa que el último ping no traía código de salida: una URL de éxito simple,/failo/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 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 en la consola de Pocket Alert, crea uno llamado Healthchecks y define la plantilla del mensaje:
%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:
{"name": $NAME_JSON, "status": "$STATUS", "time": "$NOW", "code": "$CODE", "log": $BODY_JSON, "level": "high"}
Up:
{"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:
#!/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:
POCKETALERT_API_KEY=your-api-key
15 3 * * * /usr/local/bin/cron-alert "nightly backup" /usr/local/bin/backup.sh
Algunas decisiones deliberadas:
--form-stringen lugar de JSON. La API acepta datos de formulario multipart, y--form-stringenvía la salida tal cual, con comillas y saltos de línea, sinjqni escapado. Con-Fnormal, un valor que empiece por@o<se trataría como un archivo.tail -c 2000conserva el final de la salida, donde suele estar el error.--retry-max-time 30es importante. Si se supera el límite diario de mensajes, la API responde429con unRetry-Aftercon los segundos hasta medianoche UTC, y el--retryde curl lo respeta. En nuestra prueba, sin este flag curl esperóRetry-After: 30000hasta 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
MAILTOsiguen 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 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. Un401significa que la cabeceraTokenes incorrecta. Un400suele indicar que el cuerpo no es JSON válido: comprueba que usaste$NAME_JSONsin 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
lowno 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 explica cómo enviar una push desde el propio job, alertas de copias de seguridad cubre las herramientas de backup, y la guía de Proxmox trata las copias de seguridad en un hipervisor.
Crea una cuenta gratuita, 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.