# Monitorar tarefas cron com Healthchecks.io: notificação push no celular quando um job falha ou não roda

> Monitore tarefas cron com o Healthchecks.io, hospedado ou auto-hospedado, e receba uma notificação push no celular quando um job falhar, travar ou parar de rodar em silêncio. URLs de ping com /start e códigos de saída, flags do curl que aguentam uma rede ruim, runitor e duas formas de enviar alertas ao Pocket Alert. Também um pequeno wrapper, para quando você não quer mais um serviço.

*27.10.2026*

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

Uma tarefa cron pode quebrar de duas formas. Ela pode rodar e falhar: o `pg_dump` não consegue acessar o banco, o disco está cheio. Ou pode simplesmente deixar de rodar: uma linha do crontab é apagada, o servidor é recriado sem ela, o daemon do cron morreu. A primeira forma deixa um erro em algum lugar. A segunda não deixa nada, e você só descobre no dia em que precisa do backup de ontem.

Um alerta que espera o job dizer "falhei" nunca ouve um job que não começou. Para pegar esse caso, você precisa da configuração oposta: o job avisa toda vez que termina, e outra coisa dispara o alarme quando o aviso não chega.

Este guia monta isso com o [Healthchecks.io](https://healthchecks.io), o monitor de cron de código aberto, e envia os alertas para o seu celular com o Pocket Alert. Falhas chegam com alto impacto, recuperações chegam de forma discreta. Tudo abaixo foi testado com a imagem Docker do Healthchecks v5.0.3 auto-hospedada e funciona da mesma forma no serviço hospedado.

## O que você precisa

- Uma conta no healthchecks.io (o plano Hobbyist gratuito monitora 20 jobs), ou sua própria instância a partir da imagem Docker `healthchecks/healthchecks`.
- O aplicativo Pocket Alert no seu [iPhone ou Android](/get-app) e uma chave de API em [Chaves de API](/account/apikeys). O plano gratuito já basta para começar.
- `curl` na máquina que roda as tarefas cron.

## O dead man's switch

O Healthchecks chama isso de monitoramento por heartbeat, um tipo de dead man's switch. Cada job recebe uma **verificação** com uma URL de ping única, que o job requisita quando termina. Se a próxima requisição não chegar a tempo, a verificação fica **inativa** e os alertas são enviados.

Duas configurações definem o que é "a tempo":

- **Período** é com que frequência você espera um ping: a cada hora, todo dia.
- **Tempo de tolerância** é quanto o Healthchecks espera depois do horário previsto antes de declarar a verificação inativa. Defina um valor maior que o tempo habitual do job, com uma folga.

Para uma tarefa cron, escolha o tipo de agendamento **Cron** e cole a expressão do seu crontab, além do fuso horário do servidor. Assim o Healthchecks espera pings nos horários certos do dia, e não apenas em intervalos corretos. O [editor de expressões cron](/tools/cron) explica o que cada expressão significa.

No nosso teste, uma verificação com agendamento `*/2 * * * *` e tolerância de um minuto recebeu um ping às 16:09:13. Nada pingou às 16:10, e a verificação ficou inativa às 16:11:00, exatamente um período de tolerância depois.

A URL de ping tem algumas variantes:

<div class="cmp-table-wrap">
<table class="cmp-table">
<thead><tr><th>Requisição</th><th>Significado</th></tr></thead>
<tbody>
<tr><th><code>https://hc-ping.com/&lt;uuid&gt;</code></th><td>Sucesso. O job terminou.</td></tr>
<tr><th><code>https://hc-ping.com/&lt;uuid&gt;/start</code></th><td>O job começou. O Healthchecks agora espera um sucesso dentro do tempo de tolerância e registra a duração da execução.</td></tr>
<tr><th><code>https://hc-ping.com/&lt;uuid&gt;/fail</code></th><td>O job falhou. A verificação fica inativa imediatamente.</td></tr>
<tr><th><code>https://hc-ping.com/&lt;uuid&gt;/&lt;0-255&gt;</code></th><td>Um código de saída. <code>0</code> conta como sucesso, qualquer outro valor como falha.</td></tr>
</tbody>
</table>
</div>

Em uma instância auto-hospedada, a base é o seu próprio domínio mais `/ping/`, por exemplo `https://hc.example.com/ping/<uuid>`.

## Configure a tarefa cron

Crie uma verificação, copie a URL de ping e altere a linha do crontab. Rodamos isso com o daemon do cron no 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=` é uma variável do crontab, que o shell expande no comando. A linha faz três coisas:

- Envia `/start`, então um job que trava fica inativo quando o tempo de tolerância acaba. No nosso teste, um `/start` sem continuação deixou a verificação inativa exatamente um período de tolerância depois.
- Executa o job.
- Envia `$?`, o código de saída do job. Uma execução limpa envia `/0`, uma falha envia `/2` ou o que o script retornou, e a verificação fica inativa imediatamente.

As flags do curl evitam que o ping cause problemas próprios:

- **`-m 10`** limita cada requisição a 10 segundos. Um `/start` travado não pode segurar o job.
- **`--retry 5`** repete timeouts e respostas 408, 429, 500, 502, 503 e 504, com intervalos crescentes. Um pacote perdido não deve acionar um alerta.
- **`-fsS`** faz o curl falhar em erros HTTP e ficar em silêncio, a menos que algo dê errado, para o cron não enviar por e-mail a barra de progresso do curl.
- **`-o /dev/null`** descarta o corpo da resposta, que é apenas `OK`.

Se o job for um pipeline como `pg_dump | gzip > dump.gz`, o código de saída é o do `gzip`, não o do `pg_dump`. Mova-o para um script com `set -o pipefail` no bash, para que um dump com falha não seja reportado como sucesso.

### Ou deixe o runitor fazer isso

O [runitor](https://github.com/bdd/runitor) é um pequeno binário em Go que envolve um comando e cuida dos pings: `/start` antes, o código de saída depois, e os últimos 10.000 bytes da saída do comando anexados ao 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
```

A linha do crontab fica mais curta:

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

Para uma instância auto-hospedada, adicione `HC_API_URL=https://hc.example.com/ping`. Rodamos o runitor v1.4.1 assim no cron: um backup com falha deixou a verificação inativa com código de saída 2, e a saída de erro apareceu no alerta.

## Envie alertas ao Pocket Alert

O Healthchecks se conecta ao Pocket Alert pela integração genérica **Webhook**. Vá em **Integrações**, encontre **Webhook** e clique em **Adicionar integração**. O formulário tem duas seções, "Executar quando uma verificação ficar inativa" e "Executar quando uma verificação voltar", cada uma com sua própria URL, método, corpo e cabeçalhos. Essa divisão permite que o alerta de "inativa" seja forte e o de "voltou" seja discreto.

As duas seções aceitam marcadores: `$NAME`, `$NAME_JSON`, `$STATUS`, `$NOW`, `$CODE`, `$SLUG`, `$TAGS`, `$EXITSTATUS`, `$BODY`, `$BODY_JSON`, `$JSON` e mais alguns. Para corpos JSON, atenção à diferença: `$NAME` é colado sem tratamento, então uma verificação chamada `Nightly "db" backup` quebra o JSON, enquanto `$NAME_JSON` é uma string JSON completa, com aspas incluídas. O mesmo vale para `$BODY` e `$BODY_JSON`.

### Opção 1: direto para a API

Na seção de **inativa**, escolha `POST` e a URL `https://api.pocketalert.app/v1/messages`. Cabeçalhos da requisição, um por linha:

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

Corpo da requisição:

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

Na seção de **voltou**, o mesmo método, URL e cabeçalhos, e um corpo mais discreto:

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

Clique em **Salvar integração**. Uma nova integração é vinculada a todas as verificações existentes do projeto. Isto é o que o Healthchecks enviou quando nossa verificação de teste falhou:

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

Algumas observações sobre este corpo:

- **`high` é urgente.** Ele fura o Foco e o resumo programado. Em um plano pago, troque para `critical` e um job de backup parado acorda você mesmo com o modo silencioso e o Não perturbe ativados. No plano gratuito, `critical` é aceito e entregue como `high`.
- **`low` para recuperações.** "Back up" aparece no feed sem som. Você quer saber, mas não às 3 da manhã.
- **`$EXITSTATUS` diferencia falha de ausência.** É o código de saída do último ping antes do alerta. `2` significa que o job rodou e retornou 2. Uma notificação de inatividade com `0` significa que a última execução teve sucesso e a seguinte nunca aconteceu. `-1` significa que o último ping não trouxe código de saída: uma URL de sucesso simples, `/fail` ou `/start`.
- **O botão** abre a verificação no Healthchecks. Em uma instância auto-hospedada, coloque o seu próprio domínio na URL. [Botões de ação](/features/action-buttons) são um recurso pago; no plano gratuito são removidos e a mensagem é entregue normalmente.

### Opção 2: um webhook do Pocket Alert com template

A segunda forma envia um pequeno documento JSON para um webhook do Pocket Alert, que formata a notificação push. A vantagem: ele pode incluir a saída do job.

Abra [Webhooks](/webhooks) no console do Pocket Alert, crie um chamado `Healthchecks` e defina o template da mensagem:

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

Deixe **Prioridade padrão** sem seleção, porque o payload traz o próprio nível. Copie a URL do webhook, que tem o formato `https://p4a.me/wh/abc123xyz`. A URL é o segredo, então trate-a como uma senha.

No Healthchecks, crie a integração de webhook com essa URL como `POST` nas duas seções, o cabeçalho `Content-Type: application/json` e estes corpos. Inativa:

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

Voltou:

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

`$BODY_JSON` é o corpo do último ping, que é onde o runitor coloca a saída do job. Quando o backup envolvido pelo runitor falhou no nosso teste, a notificação mostrou:

> **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

O Pocket Alert lê o campo `level` de primeiro nível de um payload recebido, então `high` e `low` funcionam como na Opção 1. Sem o runitor, `$BODY_JSON` é uma string vazia e a segunda linha fica em branco. A API não consegue fazer isso: `$BODY_JSON` é uma string JSON completa, então só pode ser a `message` inteira, e quando o ping não tinha corpo essa mensagem fica vazia e a API a rejeita.

Mais duas diferenças: o título da notificação é sempre `Webhook <name>`, então o nome da verificação vai para a mensagem, e os botões de webhook são definidos pelo campo `actions` da API de webhooks, não pelo formulário do console.

### Teste

Na página **Integrações** do Healthchecks, cada integração tem um botão **Test!**. Ele envia uma notificação de "inativa" para uma verificação chamada `TEST`, que chega como uma notificação push `high`. Depois, rode um job que termine com `1` e veja o alerta real chegar.

## Sem o Healthchecks: um wrapper que envia push na falha

Se você não quer mais um serviço, um pequeno wrapper cobre o caso mais comum: um job que termina com erro. Salve-o 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"
```

E no crontab:

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

Algumas escolhas deliberadas:

- **`--form-string` em vez de JSON.** A API aceita dados de formulário multipart, e `--form-string` envia a saída como está, com aspas e quebras de linha, sem `jq` nem escape. O `-F` simples trataria um valor começando com `@` ou `<` como um arquivo.
- **`tail -c 2000`** mantém o fim da saída, onde geralmente está o erro.
- **`--retry-max-time 30`** é importante. Acima do limite diário de mensagens, a API responde `429` com um `Retry-After` com os segundos até a meia-noite UTC, e o `--retry` do curl respeita isso. No nosso teste, sem essa flag, o curl ficou esperando `Retry-After: 30000` até o matarmos. Com ela, o curl desiste após uma tentativa.
- **O wrapper preserva o código de saída e imprime a saída**, então os logs do cron e o `MAILTO` continuam funcionando como antes.

Ele passa no shellcheck, e rodando no cron do Debian 13 o backup com falha chegou como "Cron failed: nightly backup on" seguido do hostname, com o erro do `pg_dump` no texto.

Seja claro sobre o que isso não faz. O wrapper só roda quando o cron o executa. Se a linha do crontab for apagada, o daemon cair ou a máquina estiver desligada, nada é enviado: é a falha silenciosa do início deste artigo. Um job que trava para sempre também passa despercebido. Para esses casos você precisa de algo fora da máquina esperando um heartbeat, que é para isso que serve o Healthchecks. A [CLI do Pocket Alert](/tools/cli) pode substituir a chamada ao `curl`, se você preferir.

## Limites honestos

- **O Healthchecks precisa estar no ar para perceber algo.** No serviço hospedado, isso é responsabilidade deles. Se você auto-hospedar na mesma máquina das tarefas cron, uma máquina caída derruba o monitor junto. Rode-o em outro lugar.
- **O template do corpo é limitado a 1.000 caracteres** no Healthchecks. Isso basta para os corpos acima, mas não para uma mensagem longa escrita à mão.
- **Saídas longas são cortadas na notificação push.** A notificação carrega cerca de 3 KB do início da mensagem; o texto completo fica no histórico de mensagens do aplicativo.
- **Cada alerta é uma mensagem.** Um job instável que cai e volta a cada poucos minutos envia uma notificação a cada vez, e no limite de 50 mensagens por dia do plano gratuito isso soma rápido. Corrija o job ou aumente o tempo de tolerância.

## Se nada chegar

- **Use primeiro o botão Test!.** Se o teste chegar, mas os alertas reais não, verifique se a integração está habilitada para essa verificação, na página da própria verificação.
- **Veja a página Integrações no Healthchecks.** Uma integração com falha aparece marcada como **Failed**; passe o mouse sobre ela para ver o último erro, como `Received status code 401`. Um `401` significa que o cabeçalho `Token` está errado. Um `400` geralmente significa que o corpo não é um JSON válido: confira se você usou `$NAME_JSON` sem aspas ao redor, e não `"$NAME"`.
- **Uma verificação nova não alerta até o primeiro ping.** Até lá ela está "nova", não "inativa".
- **Confira o fuso horário das verificações de cron.** Se uma verificação sempre aparece uma hora adiantada ou atrasada, o fuso horário do servidor não bate com o da verificação.
- **Olhe o feed.** Notificações `low` não fazem som, então uma recuperação pode parecer que nunca chegou.

## FAQ

### Devo usar a rota da API ou a do webhook?

A rota da API coloca o nome da verificação no título da notificação e não precisa de nada criado no Pocket Alert. A rota do webhook pode incluir a saída do job, então, com o runitor, escolha o webhook.

### Posso receber só os alertas de "inativa"?

Sim. Use um corpo `low` discreto para "voltou", como acima, ou deixe a URL de "voltou" vazia e o Healthchecks não envia nada na recuperação.

### E os timers do systemd?

A ideia é a mesma. O Healthchecks tem um tipo de agendamento **OnCalendar** que aceita as mesmas expressões do seu timer. Envie `/start` a partir de `ExecStartPre`, ou envolva o comando `ExecStart` com o runitor.

### Onde posso ler mais sobre alertas de cron?

A página [alertas de tarefas cron](/use-cases/cron-job-alerts) explica como enviar uma notificação push a partir do próprio job, os [alertas de backup](/use-cases/backup-alerts) cobrem ferramentas de backup, e o [guia do Proxmox](/blog/proxmox-alerts) trata de backups em um hypervisor.

[Crie uma conta gratuita](/signup), adicione uma integração de webhook no Healthchecks e deixe que o job que parou de rodar em silêncio seja quem acorda você.
