# Healthchecks.io로 크론 작업 모니터링: 작업이 실패하거나 실행되지 않으면 휴대폰으로 푸시 알림

> Healthchecks.io로 크론 작업을 모니터링하세요. 호스팅 서비스든 셀프 호스팅이든 상관없이, 작업이 실패하거나 멈추거나 조용히 실행을 멈추면 휴대폰으로 푸시 알림을 받을 수 있습니다. /start와 종료 코드를 사용하는 핑 URL, 불안정한 네트워크에서도 버티는 curl 옵션, runitor, 그리고 Pocket Alert로 알림을 보내는 두 가지 방법을 소개합니다. 별도 서비스를 쓰고 싶지 않다면 작은 래퍼 스크립트도 함께 제공합니다.

*27.10.2026*

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

크론 작업은 두 가지 방식으로 망가질 수 있습니다. 실행은 되지만 실패하는 경우입니다. `pg_dump`가 데이터베이스에 연결하지 못하거나 디스크가 가득 찰 수 있습니다. 다른 하나는 아예 실행되지 않는 경우입니다. crontab 줄이 삭제되거나, 설정 없이 서버를 다시 구축하거나, cron 데몬이 죽어 있을 수 있습니다. 앞의 경우에는 어딘가에 오류가 남습니다. 뒤의 경우에는 아무것도 남지 않아서, 어젯밤 백업이 필요한 날에야 문제를 알게 됩니다.

작업이 "실패했다"고 알려 주기를 기다리는 알림 방식으로는 시작조차 하지 않은 작업을 잡아낼 수 없습니다. 이를 잡으려면 반대 방향의 구성이 필요합니다. 작업이 끝날 때마다 보고를 보내고, 그 보고가 오지 않을 때 다른 쪽에서 경보를 울리는 방식입니다.

이 가이드는 오픈소스 크론 모니터링 도구인 [Healthchecks.io](https://healthchecks.io)로 이 구성을 만들고, 알림은 Pocket Alert로 휴대폰에 보내는 방법을 다룹니다. 실패는 강하게, 복구는 조용하게 알려 줍니다. 아래 내용은 셀프 호스팅 Healthchecks v5.0.3 Docker 이미지에서 테스트했고, 호스팅 서비스에서도 동일하게 동작합니다.

## 준비물

- healthchecks.io 계정(무료 Hobbyist 플랜은 작업 20개를 모니터링할 수 있습니다), 또는 `healthchecks/healthchecks` Docker 이미지로 직접 설치한 인스턴스.
- 휴대폰에 설치한 Pocket Alert 앱([iPhone 또는 Android](/get-app))과 [API 키](/account/apikeys) 페이지에서 발급받은 API 키. 시작하는 데는 무료 플랜으로 충분합니다.
- 크론 작업을 실행하는 기기에 설치된 `curl`.

## 데드 맨 스위치

Healthchecks는 이를 하트비트 모니터링, 즉 일종의 데드 맨 스위치라고 부릅니다. 작업마다 **체크**가 하나씩 생기고, 이 체크에는 고유한 핑 URL이 있습니다. 작업이 끝날 때 이 URL로 요청을 보냅니다. 다음 요청이 제시간에 도착하지 않으면 체크가 **다운** 상태가 되고 알림이 발송됩니다.

"제시간"은 두 설정으로 정해집니다.

- **주기**는 핑을 얼마나 자주 받을지 정합니다. 매시간, 매일 같은 식입니다.
- **유예 시간**은 예상 시각이 지난 뒤 Healthchecks가 다운으로 판단하기까지 기다리는 시간입니다. 작업이 보통 걸리는 시간에 여유분을 더해서 설정하세요.

크론 작업이라면 일정 유형으로 **Cron**을 고르고, crontab에 있는 표현식과 서버의 시간대를 입력하세요. 그러면 Healthchecks는 일정한 간격이 아니라 하루 중 정해진 시각에 핑이 올 것으로 기대합니다. [크론 표현식 편집기](/tools/cron)에서 표현식의 의미를 자세히 확인할 수 있습니다.

테스트에서는 일정 `*/2 * * * *`에 유예 시간 1분으로 설정한 체크가 16:09:13에 핑을 받았습니다. 16:10에는 아무 핑도 오지 않았고, 체크는 정확히 유예 시간 한 번이 지난 16:11:00에 다운되었습니다.

핑 URL에는 여러 변형이 있습니다.

<div class="cmp-table-wrap">
<table class="cmp-table">
<thead><tr><th>요청</th><th>의미</th></tr></thead>
<tbody>
<tr><th><code>https://hc-ping.com/&lt;uuid&gt;</code></th><td>성공. 작업이 끝났습니다.</td></tr>
<tr><th><code>https://hc-ping.com/&lt;uuid&gt;/start</code></th><td>작업 시작. Healthchecks는 유예 시간 안에 성공 보고가 오기를 기다리고 실행 시간을 기록합니다.</td></tr>
<tr><th><code>https://hc-ping.com/&lt;uuid&gt;/fail</code></th><td>작업 실패. 체크가 즉시 다운됩니다.</td></tr>
<tr><th><code>https://hc-ping.com/&lt;uuid&gt;/&lt;0-255&gt;</code></th><td>종료 상태. <code>0</code>은 성공, 그 외 값은 실패로 처리합니다.</td></tr>
</tbody>
</table>
</div>

셀프 호스팅 인스턴스에서는 기본 주소가 자신의 도메인과 `/ping/`입니다. 예를 들어 `https://hc.example.com/ping/<uuid>`처럼 씁니다.

## 크론 작업에 연결하기

체크를 만들고 핑 URL을 복사한 뒤 crontab 줄을 수정하세요. 우리는 Debian 13의 cron 데몬에서 이를 실행했습니다.

```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=`은 crontab 변수이며, 명령 안에서 셸이 확장합니다. 이 줄은 세 가지 일을 합니다.

- `/start`를 보냅니다. 그래서 멈춘 작업은 유예 시간이 지나면 다운 처리됩니다. 테스트에서는 뒤따르는 요청 없이 `/start`만 보냈을 때 체크가 정확히 유예 시간 한 번 뒤에 다운되었습니다.
- 작업을 실행합니다.
- 작업의 종료 상태인 `$?`를 보냅니다. 정상 종료면 `/0`을, 실패하면 `/2` 또는 스크립트가 반환한 값을 보내고, 체크는 바로 다운됩니다.

curl 옵션은 핑 자체가 문제를 일으키지 않도록 막아 줍니다.

- **`-m 10`**은 각 요청을 10초로 제한합니다. 멈춘 `/start` 때문에 작업이 지연되면 안 되기 때문입니다.
- **`--retry 5`**는 시간 초과와 408, 429, 500, 502, 503, 504 응답을 점점 길어지는 간격으로 재시도합니다. 패킷 하나가 유실됐다고 호출이 울리면 곤란하니까요.
- **`-fsS`**는 HTTP 오류가 나면 curl이 실패하게 하고, 문제가 없으면 조용히 있게 합니다. 그래서 cron이 curl의 진행 표시줄을 메일로 보내지 않습니다.
- **`-o /dev/null`**은 응답 본문을 버립니다. 본문은 `OK`뿐입니다.

작업이 `pg_dump | gzip > dump.gz` 같은 파이프라인이라면, 종료 상태는 `gzip`가 아니라 `pg_dump`의 상태입니다. bash에서 `set -o pipefail`을 설정한 스크립트로 옮겨서, 덤프가 실패했는데도 성공으로 보고되지 않도록 하세요.

### runitor에 맡기기

[runitor](https://github.com/bdd/runitor)는 명령을 감싸서 핑을 대신 처리해 주는 작은 Go 바이너리입니다. 실행 전에는 `/start`를, 실행 후에는 종료 상태를 보내고, 명령 출력의 마지막 10,000바이트를 핑에 첨부합니다.

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

이제 crontab 줄이 더 짧아집니다.

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

셀프 호스팅 인스턴스라면 `HC_API_URL=https://hc.example.com/ping`을 추가하세요. 우리는 runitor v1.4.1을 이 방식으로 cron에서 실행했습니다. 백업이 실패하자 체크가 종료 상태 2와 함께 다운되었고, 오류 출력이 알림에 그대로 담겨 왔습니다.

## Pocket Alert로 알림 보내기

Healthchecks는 범용 **Webhook** 연동을 통해 Pocket Alert에 연결됩니다. **Integrations**로 이동해 **Webhook**을 찾고 **Add Integration**을 클릭하세요. 폼에는 "Execute when a check goes down"과 "Execute when a check goes up" 두 섹션이 있고, 각각 고유한 URL, 메서드, 본문, 헤더를 설정합니다. 이렇게 나뉘어 있어서 "다운"은 강하게, "업"은 조용하게 보낼 수 있습니다.

두 섹션 모두 `$NAME`, `$NAME_JSON`, `$STATUS`, `$NOW`, `$CODE`, `$SLUG`, `$TAGS`, `$EXITSTATUS`, `$BODY`, `$BODY_JSON`, `$JSON` 등 여러 플레이스홀더를 사용할 수 있습니다. JSON 본문에서는 차이를 주의하세요. `$NAME`은 그대로 붙여 넣으므로, `Nightly "db" backup`이라는 이름이면 JSON이 깨집니다. 반면 `$NAME_JSON`은 따옴표까지 포함된 완전한 JSON 문자열입니다. `$BODY`와 `$BODY_JSON`도 같은 관계입니다.

### 방법 1: API로 직접 보내기

**down** 섹션에서 `POST`를 고르고 URL은 `https://api.pocketalert.app/v1/messages`로 설정하세요. 요청 헤더는 한 줄에 하나씩 입력합니다.

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

요청 본문:

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

**up** 섹션에는 메서드, URL, 헤더는 같게 두고 더 조용한 본문을 넣습니다.

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

**Save Integration**을 클릭하세요. 새 연동은 프로젝트의 기존 체크 전체에 연결됩니다. 아래는 테스트 체크가 실패했을 때 Healthchecks가 보낸 내용입니다.

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

이 본문에 대한 몇 가지 참고 사항입니다.

- **`high`는 시간에 민감한 알림입니다.** 집중 모드와 예약 요약을 뚫고 전달됩니다. 유료 플랜에서는 `critical`로 바꾸면 백업 작업이 죽었을 때 무음 스위치와 방해 금지 모드에서도 깨워 줍니다. 무료 플랜에서는 `critical`도 받아들이지만 `high`로 전달됩니다.
- **복구에는 `low`를 씁니다.** "Back up" 알림은 소리 없이 피드에 쌓입니다. 알아야 하지만 새벽 3시에 깨울 필요는 없는 알림이기 때문입니다.
- **`$EXITSTATUS`로 실패와 누락을 구분할 수 있습니다.** 알림 직전 마지막 핑의 종료 상태입니다. `2`는 작업이 실행되어 2를 반환했다는 뜻입니다. `0`과 함께 다운되었다면 마지막 실행은 성공했는데 다음 실행이 오지 않았다는 뜻입니다. `-1`은 마지막 핑에 종료 상태가 없었다는 뜻입니다. 단순 성공 URL, `/fail`, `/start` 중 하나입니다.
- **버튼**은 Healthchecks에서 해당 체크를 엽니다. 셀프 호스팅 인스턴스라면 URL에 자신의 도메인을 넣으세요. [액션 버튼](/features/action-buttons)은 유료 기능입니다. 무료 플랜에서는 버튼이 제거되고 메시지 자체는 평소처럼 전달됩니다.

### 방법 2: 템플릿을 쓰는 Pocket Alert 웹훅

두 번째 방법은 작은 JSON 문서를 Pocket Alert 웹훅으로 보내면 Pocket Alert가 푸시를 구성하는 방식입니다. 장점은 작업의 출력을 포함할 수 있다는 것입니다.

Pocket Alert 콘솔의 [웹훅](/webhooks)을 열고 `Healthchecks`라는 이름으로 하나 만든 뒤, 메시지 템플릿을 설정하세요.

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

페이로드가 자체 레벨을 가지므로 **Default priority**는 선택하지 마세요. 웹훅 URL을 복사하면 `https://p4a.me/wh/abc123xyz`처럼 생겼습니다. 이 URL 자체가 비밀이므로 비밀번호처럼 다루세요.

Healthchecks에서는 이 URL을 사용해 웹훅 연동을 만듭니다. 두 섹션 모두 `POST`로 설정하고, 헤더는 `Content-Type: application/json`을 넣고, 본문은 다음과 같이 입력합니다. 다운일 때:

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

업일 때:

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

`$BODY_JSON`은 마지막 핑의 본문이며, runitor가 작업 출력을 넣는 곳이 바로 여기입니다. 테스트에서 runitor로 감싼 백업이 실패했을 때 푸시에는 다음이 표시되었습니다.

> **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는 들어오는 페이로드의 최상위 `level` 필드를 읽으므로, `high`와 `low`는 방법 1과 똑같이 동작합니다. runitor를 쓰지 않으면 `$BODY_JSON`은 빈 문자열이 되고 둘째 줄은 비어 있습니다. API로는 이 방식을 쓸 수 없습니다. `$BODY_JSON`은 완전한 JSON 문자열이라 `message` 전체가 되어야 하는데, 핑에 본문이 없으면 메시지가 비게 되어 API가 요청을 거부합니다.

그 밖의 차이점도 있습니다. 푸시 제목은 항상 `Webhook <name>` 형식이므로 체크 이름은 메시지에 넣어야 합니다. 또 웹훅 버튼은 콘솔 폼이 아니라 웹훅 API의 `actions` 필드로 설정합니다.

### 테스트하기

Healthchecks **Integrations** 페이지에서는 연동마다 **Test!** 버튼이 있습니다. `TEST`라는 이름의 체크에 대한 "다운" 알림을 보내며, `high` 푸시로 도착합니다. 그다음 종료 코드 `1`로 끝나는 작업을 실행해서 실제 알림이 도착하는지 확인하세요.

## Healthchecks 없이: 실패 시 푸시를 보내는 래퍼

또 다른 서비스를 원하지 않는다면, 짧은 래퍼 스크립트로 가장 흔한 경우, 즉 오류 종료하는 작업을 처리할 수 있습니다. `/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"
```

그리고 crontab에는 다음과 같이 넣습니다.

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

몇 가지 의도적인 선택이 있습니다.

- **JSON 대신 `--form-string`을 씁니다.** API는 멀티파트 폼 데이터를 받으며, `--form-string`은 따옴표와 줄바꿈을 포함해 출력을 그대로 보냅니다. `jq`나 이스케이프 처리가 필요 없습니다. 일반 `-F`를 쓰면 `@`나 `<`로 시작하는 값을 파일로 취급합니다.
- **`tail -c 2000`**은 출력의 끝부분을 남깁니다. 오류는 보통 거기에 있기 때문입니다.
- **`--retry-max-time 30`**이 중요합니다. 일일 메시지 한도를 넘으면 API는 `429`와 함께 자정 UTC까지 남은 초를 담은 `Retry-After`를 응답하는데, curl의 `--retry`는 이 값을 따릅니다. 테스트에서 이 옵션이 없을 때 curl은 `Retry-After: 30000`을 기다리며 멈춰 있었고, 우리가 직접 종료해야 했습니다. 이 옵션이 있으면 curl은 한 번 시도한 뒤 포기합니다.
- **래퍼는 종료 상태를 유지하고 출력을 그대로 보여 줍니다.** 그래서 cron 로그와 `MAILTO`도 예전처럼 동작합니다.

shellcheck도 통과하며, Debian 13의 cron에서 실행했을 때 실패한 백업은 "Cron failed: nightly backup on"과 호스트 이름으로 시작하고, 본문에 `pg_dump` 오류가 담긴 알림으로 도착했습니다.

이 방식의 한계도 분명히 해 두겠습니다. 래퍼는 cron이 실행할 때만 동작합니다. crontab 줄이 삭제되었거나, 데몬이 중지되었거나, 기기가 꺼져 있다면 아무것도 전송되지 않습니다. 이 글의 시작 부분에서 말한 조용한 실패 그대로입니다. 영원히 멈춰 있는 작업도 알아채지 못합니다. 이런 경우에는 기기 바깥에서 하트비트를 기다리는 무언가가 필요하며, 그것이 바로 Healthchecks의 역할입니다. 다른 방법을 선호한다면 [Pocket Alert CLI](/tools/cli)로 `curl` 호출을 대체할 수도 있습니다.

## 솔직한 한계

- **알림을 받으려면 Healthchecks가 살아 있어야 합니다.** 호스팅 서비스에서는 이 일을 그쪽에서 맡습니다. 크론 작업과 같은 기기에 셀프 호스팅하면, 기기가 죽을 때 모니터도 함께 죽습니다. 다른 곳에서 실행하세요.
- **본문 템플릿은 Healthchecks에서 1,000자로 제한됩니다.** 위 예시 본문에는 충분하지만, 길게 직접 쓴 메시지에는 부족합니다.
- **긴 출력은 푸시에서 잘립니다.** 푸시에는 메시지의 앞부분 약 3KB만 담깁니다. 전체 텍스트는 앱의 메시지 기록에 있습니다.
- **알림 하나는 메시지 하나입니다.** 몇 분 간격으로 다운과 업을 반복하는 작업은 그때마다 푸시를 보냅니다. 무료 플랜의 하루 50개 메시지 한도는 금방 찹니다. 작업을 고치거나 유예 시간을 늘리세요.

## 알림이 도착하지 않는다면

- **먼저 Test! 버튼을 누르세요.** 테스트 알림은 오는데 실제 알림이 오지 않는다면, 해당 체크 페이지에서 연동이 그 체크에 활성화되어 있는지 확인하세요.
- **Healthchecks의 Integrations 페이지를 보세요.** 실패한 연동에는 **Failed** 표시가 붙습니다. 마우스를 올리면 `Received status code 401` 같은 마지막 오류를 볼 수 있습니다. `401`은 `Token` 헤더가 잘못되었다는 뜻입니다. `400`은 보통 본문이 올바른 JSON이 아니라는 뜻이니, `$NAME_JSON`을 따옴표 없이 썼는지, `"$NAME"`으로 쓰지 않았는지 확인하세요.
- **새 체크는 첫 핑을 받기 전까지 알림을 보내지 않습니다.** 그 전까지는 "다운"이 아니라 "새 체크" 상태입니다.
- **크론 체크의 시간대를 확인하세요.** 체크가 항상 한 시간 빠르거나 늦다면, 서버의 시간대와 체크에 설정한 시간대가 맞지 않는 것입니다.
- **피드를 확인하세요.** `low` 푸시는 소리가 나지 않으므로, 복구 알림이 아예 오지 않은 것처럼 보일 수 있습니다.

## 자주 묻는 질문

### API 방식과 웹훅 방식 중 무엇을 써야 하나요?

API 방식은 체크 이름을 푸시 제목에 넣으며, Pocket Alert에서 따로 만들 것이 없습니다. 웹훅 방식은 작업의 출력을 포함할 수 있으므로, runitor를 쓴다면 웹훅을 선택하세요.

### "다운" 알림만 받을 수 있나요?

네. 위에서 설명한 것처럼 "업"에는 조용한 `low` 본문을 쓰거나, "업" URL을 비워 두세요. 그러면 복구 시 Healthchecks가 아무것도 보내지 않습니다.

### systemd 타이머는 어떻게 하나요?

원리는 같습니다. Healthchecks에는 **OnCalendar** 일정 유형이 있어서 타이머와 같은 표현식을 쓸 수 있습니다. `/start`에서 `ExecStartPre`를 보내거나, `ExecStart` 명령을 runitor로 감싸세요.

### 크론 알림에 대해 더 읽을 곳이 있나요?

[크론 작업 알림](/use-cases/cron-job-alerts) 페이지에서는 작업 자체에서 푸시를 보내는 방법을, [백업 알림](/use-cases/backup-alerts) 페이지에서는 백업 도구를 다룹니다. [Proxmox 가이드](/blog/proxmox-alerts)에서는 하이퍼바이저의 백업을 설명합니다.

[무료 계정을 만들고](/signup), Healthchecks에 웹훅 연동을 하나 추가해 보세요. 조용히 멈춰 버린 작업이 이제 여러분을 깨우게 될 것입니다.
