Cron / heartbeat checks

A cron check (also called a heartbeat or deadman’s switch) is the inverse of an HTTP check. Instead of Site Qwality calling your service, your service calls Site Qwality at the end of each successful run. Site Qwality alerts when the expected ping doesn’t arrive on time.

# At the end of your nightly backup script
curl -X POST https://ping.siteqwality.com/<account-id>/<cron-job-id>

A heartbeat that keeps flipping between late and on time is held like a flapping HTTP monitor: see flap hold.

When to use cron checks

• Backups, ETL jobs, batch jobs. You want to know when they don’t complete, not just when the host is up.
• Cleanup tasks (purge old data, rotate logs, compact tables) where silence is the failure mode.
• External cron services (cron-job.org, EventBridge, GitHub Actions schedules) that don’t have built-in failure alerting.

When NOT to use them

• Don’t use cron checks for “is my service running?” That’s an HTTP check job.
• Don’t use them for “is the queue draining?” That’s a metric: emit one, chart it on a dashboard and alert on it with a metric threshold.

How it works

1. You create a cron check in Site Qwality with a check_interval_seconds, say 86400 for a daily job, and an optional grace_seconds for a job that can finish a little late. Site Qwality returns the check’s id.
2. Your job pings https://ping.siteqwality.com/<account-id>/<cron-job-id> at the end of every successful run, and can add /start when a run begins and /fail when it fails (how). The ping needs no API key: the URL itself is the credential, so treat it like a secret.
3. Site Qwality records each ping with a timestamp, source IP, and headers, queryable via GET /cron/job/{cron_job_id}/recent.
4. The check fails when no finished-run ping arrives within check_interval_seconds plus grace_seconds of the last one (a check that has never been pinged is measured from when you created it). Site Qwality checks every cron check once a minute, so the alert follows within about a minute.
5. A successful ping on a failed check brings it back to healthy right away.

A ping that arrives late but inside the grace counts for the run it was late for: with a 5-minute grace, a daily job that finishes at 02:05 instead of 02:00 doesn’t alert. See set a grace period.

Every field and the ping contract are in the cron check reference.

See also

Quickstart Set up a heartbeat for a daily job and test its alert.

Sending heartbeats Best practices for the actual ping in your jobs.

Set a grace period How late is too late.