Skip to main content
By the end of this guide, you’ll have a heartbeat monitor watching for periodic pings from your background job. If the ping stops arriving, DevHelm opens an incident.
  • DevHelm CLI installed or an API token for REST calls
  • An API token set as DEVHELM_API_TOKEN — see Authentication
  • A cron job, background worker, or scheduled task to monitor

​
How heartbeats work

Unlike other monitor types where DevHelm checks your service, heartbeat monitors work in reverse — your service pings DevHelm. If DevHelm doesn’t receive a ping within the expected interval plus a grace period, it opens an incident.

​
Create the monitor

1

Create the heartbeat monitor

devhelm monitors create \
  --name "Nightly Backup" \
  --type HEARTBEAT \
  --expected-interval 86400 \
  --grace-period 3600
The response includes a unique ping URL for this monitor.
2

Get the ping URL

devhelm monitors get <monitor-id>
Look for the pingUrl field — it looks like:
https://api.devhelm.io/api/v1/heartbeat/<token>
3

Add the ping to your job

Add a curl call at the end of your cron job or scheduled task:
#!/bin/bash
# Your backup script
pg_dump mydb > /backups/nightly.sql

# Ping DevHelm on success
curl -fsS -o /dev/null https://api.devhelm.io/api/v1/heartbeat/<token>
4

Verify the first ping

Run your job once and confirm the ping arrived:
devhelm monitors checks <monitor-id> --limit 1

​
Configuration fields

FieldTypeDescription
expectedIntervalintegerExpected seconds between pings (e.g., 86400 for daily)
gracePeriodintegerExtra seconds to wait before declaring the job late
The monitor opens an incident if no ping arrives within expectedInterval + gracePeriod seconds after the last ping.

​
Common patterns

For a job that runs every hour, set expectedInterval: 3600 and gracePeriod: 300 (5 minutes of slack).
Add a curl sidecar or post-completion hook that pings DevHelm after the job container exits successfully.
For long-running workers that process queues, add a periodic heartbeat in your main loop (e.g., every 5 minutes).
Use curl -fsS so the ping is only sent on HTTP success. If your script fails, the ping is skipped and DevHelm eventually opens an incident.
Heartbeat monitors cannot have probe regions — they rely on incoming pings from your infrastructure, not outbound checks.

​
Next steps

Heartbeat reference

Full heartbeat configuration and assertion details.

Cron job monitoring

Advanced patterns for scheduled task monitoring.

First alert

Get notified when a heartbeat goes silent.