Skip to main content
Heartbeat monitoring tracks services that can’t be pinged from the outside. Your service sends periodic “heartbeat” signals, and we alert you if they stop.

​
How It Works

  1. Create a heartbeat monitor with an expected interval
  2. Your service pings the monitor at regular intervals
  3. If we don’t receive a ping within the expected window, we alert you

​
Use Cases

  • Cron jobs - Verify scheduled tasks complete
  • Background workers - Monitor queue processors
  • Batch jobs - Track ETL and data pipelines
  • Internal services - Services behind firewalls

​
Creating a Heartbeat Monitor

  1. Go to Dashboard > Heartbeat
  2. Click Add Monitor
  3. Name your monitor and set the expected interval
  4. Copy the ping URL

​
Sending Heartbeats

Add a simple HTTP call to your job: 
# At the end of your cron job
curl -X POST "https://kodostatus.com/api/v1/heartbeat/hb_abc123"

# With status
curl -X POST "https://kodostatus.com/api/v1/heartbeat/hb_abc123" \
  -H "Content-Type: application/json" \
  -d '{"status": "up", "message": "Backup completed"}'

​
Crontab Integration

# Crontab entry with heartbeat
0 2 * * * /path/to/backup.sh && curl -s https://kodostatus.com/api/v1/heartbeat/hb_abc123

​
Grace Periods

Allow some flexibility for job timing:
SettingDescription
IntervalHow often heartbeats are expected
Grace periodExtra time before marking as late
Example: 5-minute interval with 1-minute grace period means alerts fire after 6 minutes of silence.

​
Reporting Failures

Report when jobs fail: 
if /path/to/job.sh; then
  curl -X POST "https://kodostatus.com/api/v1/heartbeat/hb_abc123" \
    -d '{"status": "up"}'
else
  curl -X POST "https://kodostatus.com/api/v1/heartbeat/hb_abc123" \
    -d '{"status": "down", "message": "Job failed with exit code 1"}'
fi

​
No Authentication Required

Heartbeat endpoints don’t require API key authentication. The monitor ID acts as a secret token. Keep your monitor URLs private.