Skip to content
Aloft Docs

Heartbeat monitors

Most monitors are active: Aloft reaches out to your service and checks whether it answers. A heartbeat monitor flips that around. It’s passive — your job reaches out to Aloft on every successful run, and Aloft alerts you when an expected check-in doesn’t arrive.

That makes heartbeats the right tool for things you can’t poll from the outside: nightly backups, cron jobs, queue workers, data syncs, scheduled reports — anything that runs on a timer and should “phone home” when it finishes.

How it works

Section titled “How it works”
  1. You create a heartbeat monitor. Aloft generates a unique, opaque heartbeat URL for it.
  2. Your job sends an HTTP POST to that URL at the end of each successful run.
  3. Aloft records the time of the last heartbeat. If no heartbeat arrives within the check interval plus a grace period, the monitor goes down and an incident opens.
  4. The next successful heartbeat marks the monitor back up and closes the incident — right away, not on the next scheduled tick.

If a monitor has never received a heartbeat, it reports down with “No heartbeat ever received,” so a job that silently never ran still gets flagged.

Finding the heartbeat URL

Section titled “Finding the heartbeat URL”

Open the monitor’s detail page. A Heartbeat URL card shows the full URL plus a ready-to-paste cron + curl example. The URL looks like:

https://your-aloft-host/api/heartbeat/<token>

The <token> is the only secret — anyone who knows the URL can mark the monitor alive, so treat it like a credential. Need to rotate it? Change the monitor’s type away from heartbeat and back (via Edit) and Aloft issues a fresh token.

Wiring up your job

Section titled “Wiring up your job”

Add a single curl call at the end of your script, after the real work succeeds:

Terminal window
# Run the backup; only ping Aloft if it exits 0
pg_dump mydb > /backups/mydb.sql && \
  curl -fsS -X POST https://your-aloft-host/api/heartbeat/<token>

Or as its own crontab line right after the job:

# Nightly at 02:00, then check in
0 2 * * * /usr/local/bin/backup.sh && curl -fsS -X POST https://your-aloft-host/api/heartbeat/<token>

The && matters: it ensures the heartbeat only fires when the job actually succeeded. If the backup fails, no heartbeat is sent, the deadline passes, and Aloft alerts you — exactly what you want.

The -fsS flags make curl fail on HTTP errors and stay quiet on success, so a failed ping shows up in your job’s own logs too.

Interval vs. grace period

Section titled “Interval vs. grace period”

Two settings decide how long Aloft waits before declaring a miss:

  • Check interval — how often you expect a heartbeat. Set this to match your job’s cadence (e.g. 5 minutes for a frequent worker, daily for a nightly backup). Range is 60 seconds to 24 hours.
  • Heartbeat grace period — slack on top of the interval, to absorb normal jitter (a backup that usually takes 3 minutes but occasionally takes 6, clock skew, a slightly delayed cron). Defaults to 60 seconds, and can range from 10 seconds to 24 hours.

Aloft declares the monitor down only once interval + grace has elapsed since the last heartbeat. So a job on a 1-hour interval with the default 60-second grace must check in within 61 minutes, or it’s flagged.

Section titled “Related”