Heartbeat Monitors

Monitor cron jobs and scheduled tasks — silence means down.

What a heartbeat monitor is

Normal monitors ask "does the service answer?" — heartbeats flip it: your job tells us it ran. If no ping arrives within the expected window, the monitor goes down. It is the standard way to watch cron jobs, backups, queue workers, ETL pipelines and anything else that runs on a schedule.

Creating one

Create a monitor with type heartbeat and set expected_interval (seconds, 10–86400) — how often you expect the job to ping. The response contains the monitor's heartbeat token.

curl -X POST https://api.shxrk.systems/api/v1/uptime/monitors \
  -H "Authorization: Bearer sk_shx_..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "nightly-backup",
    "type": "heartbeat",
    "status_page_id": "<uuid>",
    "expected_interval": 90000,
    "failure_threshold": 1
  }'

Give expected_interval headroom over the real schedule — a job running every 24h at 03:00 with a 90000s (25h) window tolerates an hour of drift.

Pinging

At the end of your job, send one authenticated POST:

curl -X POST https://api.shxrk.systems/api/v1/uptime/heartbeat/<monitor_id> \
  -H "Authorization: Bearer <heartbeat_token>"

The token is also accepted as ?token=<heartbeat_token> for environments where setting headers is awkward.

Examples:

# Cron — ping only when the job succeeds
0 3 * * * /opt/backup.sh && curl -fsS -X POST "https://api.shxrk.systems/api/v1/uptime/heartbeat/<monitor_id>?token=<heartbeat_token>"

# systemd — ping from ExecStartPost, so a failed unit never pings
# ExecStartPost=/usr/bin/curl -fsS -X POST "https://api.shxrk.systems/api/v1/uptime/heartbeat/<monitor_id>?token=..."

Each ping records a successful check and resets the staleness timer — incidents, recovery and alerting behave exactly like every other monitor.

Security notes

  • The heartbeat token (hb_...) is write-only — it can only ping this one monitor. Losing it lets someone fake "alive" for that monitor, nothing more
  • Rotate it by regenerating the monitor's token if it leaks
  • Team members without settings permission never see the token — it is redacted server-side
PreviousAgentsNextOn-Call & Escalations