Heartbeat monitors

Some things can’t be probed from outside: a nightly backup, a queue worker, a report that should run every hour. A heartbeat monitor flips the direction. Instead of StatusCheck calling you, your job calls StatusCheck, and you are alerted when it doesn’t.

How it works

1. Create a heartbeat monitor with an expected period (how often the job should run) and a grace period (how late is still fine).
2. StatusCheck gives you a unique ping URL such as https://ping.statuscheck.io/h-a1b2c3d4.
3. Add a request to that URL at the end of your job, after it has succeeded.
4. If no ping arrives within period + grace, the monitor goes Down and alerts.

The next successful ping recovers the monitor.

Pinging

Any HTTP request to the ping URL counts: GET, POST, or HEAD. Examples:

# At the end of a cron entry
0 3 * * * /usr/local/bin/backup.sh && curl -fsS --retry 3 https://ping.statuscheck.io/h-a1b2c3d4 > /dev/null

# Python
import requests
requests.get("https://ping.statuscheck.io/h-a1b2c3d4", timeout=10)

Node.js

await fetch("https://ping.statuscheck.io/h-a1b2c3d4");

Use && (or the equivalent in your language) so the ping only fires when the job succeeded. A job that runs but fails should look like a missed heartbeat.

Reporting a failure explicitly

Append /fail to the ping URL to mark the monitor down immediately, without waiting for the grace period to elapse. Send the error output as the request body and it appears on the incident timeline.

/usr/local/bin/backup.sh || curl -fsS -X POST --data-binary @error.log https://ping.statuscheck.io/h-a1b2c3d4/fail

Choosing period and grace

Job	Period	Grace
Every-minute queue worker	1 minute	2 minutes
Hourly sync	1 hour	15 minutes
Nightly backup at 03:00	24 hours	2 hours
Weekly report	7 days	12 hours

The grace period should cover the job’s own run time plus normal scheduling jitter. Too short and you’ll be paged for a slow backup; too long and you’ll find out about the failure late.

What is recorded

Each ping records its arrival time and the source IP. The monitor’s chart shows the interval between pings, which makes gradual slowdowns visible long before they cause a miss.