Cron check quickstart

By the end of this guide you’ll have a cron check expecting a ping every 24 hours, your job sending the ping, and a verified failure → alert path.

1. Create the cron check

Dashboard

1. Go to Observe → Monitors, open Add monitor and choose Cron monitor.

2. Configure:

   • Name: Nightly backup.
   • Check Interval Minutes: the 24h mark (one day, 86400 seconds in the API).
   • Notification groups: leave the Default group selected.

3. Click Create monitor. The check page shows its Ping URL at the top, with a line to add to your job.

API

With an API key exported as SITEQWALITY_API_KEY:

curl -X POST https://api.siteqwality.com/cron/job \
  -H "Authorization: Bearer $SITEQWALITY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "friendly_name": "Nightly backup",
    "check_interval_seconds": 86400
  }'

With group_notification_ids left out, the check uses your Default group, as in the dashboard. The response includes id and account_id, which make the ping URL: https://ping.siteqwality.com/<account_id>/<id>. The steps below use the id as $CRON_JOB_ID.

2. Wire your job to ping

Add a single line to the end of your job, after the work has succeeded.

# Bash (at the end of nightly_backup.sh)
PING_URL="https://ping.siteqwality.com/<account-id>/<cron-job-id>"

if pg_dump $DB > backup.sql && aws s3 cp backup.sql s3://backups/; then
  curl -fsS --max-time 10 --retry 3 "$PING_URL" || true
fi

# Python
import requests

PING_URL = "https://ping.siteqwality.com/<account-id>/<cron-job-id>"

def ping():
    try:
        requests.post(PING_URL, timeout=10)
    except requests.RequestException:
        pass  # never let the ping failure kill the job

# At the end of your job
do_backup()
ping()

// Node
const PING_URL = "https://ping.siteqwality.com/<account-id>/<cron-job-id>";

async function ping() {
  try {
    await fetch(PING_URL, { method: "POST" });
  } catch {
    // intentional swallow so ping failures don't break the job
  }
}

await doBackup();
await ping();

3. Verify the heartbeat lands

Dashboard

The check’s Recent pings list shows each ping, when it arrived and who sent it, within seconds.

API

curl https://api.siteqwality.com/cron/job/$CRON_JOB_ID/recent \
  -H "Authorization: Bearer $SITEQWALITY_API_KEY"

Returns the most recent receipts.

4. Force a failure

To verify the alerting path:

1. Edit the cron check and drop Check Interval Minutes to 5m (check_interval_seconds: 300 in the API).
2. Don’t ping for 7 minutes.
3. The check flips to failed and your notification group fires.
4. Send a ping manually (curl <ping-url>). The check flips back to success right away and the group gets the all clear.

Don’t forget to set the interval back to 24h (86400) when done testing.

What’s next

Heartbeat best practices Retries, jitter, idempotency, and start-vs-end pinging.

Grace period How Site Qwality decides 'late enough to alert.'