CronBeatCronBeat

Heartbeat Monitoring

Heartbeat monitoring works on a simple principle: your cron jobs and scheduled tasks ping CronBeat after each successful run. If the expected ping doesn't arrive, CronBeat alerts you.

How It Works

  1. You create a heartbeat monitor and define the expected schedule
  2. CronBeat calculates when the next ping should arrive (based on schedule + grace period)
  3. Your job runs and pings CronBeat on completion
  4. If the ping is missed, CronBeat triggers an alert
text

Ping Key & URL

Every heartbeat monitor has a unique Ping Key — a 21-character identifier. Your ping URL is:

text

Copy the Ping Key from the Integration section on your monitor's detail page. It looks like: V1StGXR8_Z5jdHi6B-myT

A simple GET or POST to this URL registers a successful ping. That's the only endpoint you need.

Schedule Types

Heartbeat monitors support two schedule types:

Cron Expression

Use standard cron expressions to match your job's schedule exactly:

text

Examples:

ExpressionMeaning
0 2 * * *Every day at 2:00 AM
*/15 * * * *Every 15 minutes
0 0 * * 0Every Sunday at midnight
0 9 1 * *First day of each month at 9:00 AM

Fixed Interval

For jobs that run at a fixed interval rather than a cron schedule, specify the interval in seconds:

IntervalDescription
60 secondsEvery minute
300 secondsEvery 5 minutes
3600 secondsEvery hour
86400 secondsEvery day

Timezone

By default, cron expressions are evaluated in UTC. You can set a custom timezone per monitor (e.g., America/New_York, Asia/Shanghai) in the monitor settings.

Grace Period

The Grace Period is extra time CronBeat waits after the expected ping time before considering it "missed."

Example:

  • Schedule: 0 2 * * * (2:00 AM daily)
  • Grace Period: 5 minutes (default)
  • If no ping arrives by 2:05 AM, an alert is triggered

How to set the right value:

  • Too short — May cause false alerts if your job takes time to complete
  • Too long — Delays notification of real failures
  • Recommended — Set to 1.5-2x your job's typical execution time

The default grace period is 5 minutes. If your job typically takes longer than that to complete, increase the grace period accordingly.

Monitor Status

StatusMeaning
NewMonitor just created, no pings received yet
UpPings are arriving as expected
DownExpected ping was missed, alert triggered
PausedMonitoring temporarily disabled by user

Integration Examples

Crontab (Linux/macOS)

The simplest integration — append a curl command after your job:

bash

Use && to only ping on success — if the job fails, no ping is sent, and CronBeat alerts on the missed ping. Use ; if you want to ping regardless of job outcome.

Shell Script

For more complex jobs, wrap the ping in your script:

bash

Docker

dockerfile

Or in Docker Compose with a healthcheck-style approach:

yaml

Node.js

javascript

Python

python

Best Practices

  1. Use --retry 3 — Adds resilience against transient network issues
  2. Use --max-time 10 — Prevents curl from hanging indefinitely
  3. Set grace period > job duration — Avoid false positives
  4. Use && not ; — Only ping on success to catch failures
  5. Don't let ping failure break your job — Use -f (fail silently) or wrap in try/catch