Guides / Heartbeat monitoring

How to monitor cron jobs with heartbeat monitoring

A heartbeat monitor alerts you when a job stops pinging in — the opposite of a normal uptime check. Use it for cron jobs, scheduled tasks, backup scripts, and background workers.

Free plan included One curl command to set up

The silent failure problem

Normal uptime monitoring checks whether a server responds. But cron jobs and background workers fail silently — the server is up, no HTTP error is thrown, but the job just... stops running.

Without heartbeat monitoring

  • Your nightly backup script exits with an error — nobody notices for a week
  • Your invoice generation cron crashes — customers don't get invoices
  • Your email queue worker silently dies — emails stack up undelivered

With heartbeat monitoring

  • Your job pings PingBase on each successful run
  • If PingBase doesn't hear from it within the expected interval, you get an alert
  • You know within minutes, not days

How heartbeat monitoring works

1

Create a heartbeat monitor

You tell PingBase: "I have a job that should run every 60 minutes." PingBase gives you a unique ping URL.

2

Add one line to your job

At the end of your script or cron job, add a curl call to your ping URL. This tells PingBase: "The job ran successfully."

3

PingBase watches the interval

If PingBase doesn't receive a ping within the expected interval (plus a grace period), it sends you an alert: the job hasn't been heard from.

Setting up a heartbeat monitor

Step 1 — Create the monitor

curl -X POST https://pingbase-worker.workers.dev/api/monitors \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Nightly Backup",
    "monitor_type": "heartbeat",
    "interval_minutes": 1440
  }'

# Returns:
# {
#   "id": "mon_abc123",
#   "name": "Nightly Backup",
#   "monitor_type": "heartbeat",
#   "heartbeat_token": "hb_xxxxxxxxxxxxxxxx",
#   "interval_minutes": 1440,
#   "status": "pending"
# }

Set interval_minutes to how often the job should run. Default is 60 (hourly). Common values: 5, 15, 60, 1440 (daily).

Step 2 — Your ping URL

Your heartbeat monitor has a unique token. Your ping URL is:

https://pingbase-worker.workers.dev/api/heartbeat/hb_xxxxxxxxxxxxxxxx

A GET or POST to this URL counts as a successful heartbeat ping.

Step 3 — Add the ping to your job

Add a curl call at the end of your script. The ping should only fire on successful completion — not at the start, and not if the script errors.

Shell / cron script

#!/bin/bash
set -e

# ... your backup logic here ...
pg_dump mydb | gzip > /backups/mydb-$(date +%Y%m%d).sql.gz

# Ping PingBase on success
curl -fsS -m 10 https://pingbase-worker.workers.dev/api/heartbeat/hb_xxxxxxxxxxxxxxxx

The set -e ensures the ping only runs if all previous commands succeeded.

Node.js

async function runBackup() {
  // ... your job logic ...
  await processQueue();

  // Ping on success
  await fetch('https://pingbase-worker.workers.dev/api/heartbeat/hb_xxxxxxxxxxxxxxxx')
    .catch(() => {}); // don't fail the job if the ping fails
}

Python

import requests

def run_job():
    # ... your job logic ...
    process_invoices()

    # Ping on success
    try:
        requests.get('https://pingbase-worker.workers.dev/api/heartbeat/hb_xxxxxxxxxxxxxxxx', timeout=10)
    except Exception:
        pass  # don't fail the job if the ping fails

crontab entry

# Run at 2am every night, ping PingBase on success
0 2 * * * /usr/local/bin/backup.sh && curl -fsS https://pingbase-worker.workers.dev/api/heartbeat/hb_xxxxxxxxxxxxxxxx

Common use cases

🗄️

Database backups

Verify your nightly backup script completes successfully. Set interval to 1440 minutes (24 hours) and get alerted if it misses a run.

📧

Email queue worker

Background workers that process email queues can die silently. A heartbeat every 5 minutes catches it immediately.

💰

Billing / invoice generation

End-of-month invoice crons that fail silently can cause revenue loss. Monitor them with a daily heartbeat.

🔄

Data sync jobs

ETL pipelines, CRM syncs, or analytics aggregation jobs. If the sync stops, your data goes stale without any error surfacing.

Best practices

✓
Ping at the end, not the beginning. The heartbeat should confirm the job completed successfully, not just that it started.
✓
Don't let ping failures kill the job. Wrap the ping in a try/catch or use || true in shell. If PingBase is unreachable, you don't want your backup to fail because of it.
✓
Set a timeout on the ping request. Use -m 10 with curl or a 10-second timeout in your HTTP client so a slow network doesn't hold up your job.
✓
Name monitors clearly. Use names like "Nightly DB Backup" or "Invoice Cron — Monthly" so alerts are immediately actionable.

Stop missing silent cron job failures

Heartbeat monitors are included in the free plan. No credit card required.

Start free →
←

Monitor your API endpoints

HTTP checks, keywords, response time tracking