Docs

Cron heartbeats

A heartbeat watches a job that should run on a schedule: a backup, a queue worker, a nightly import. Your job calls a URL when it runs; if the call does not arrive in time, we alert you.

Setting one up

Go to Heartbeats → Add heartbeat, give it a name, and set:

  • Period: how often the job runs (every hour, every day…);
  • Grace: how late it may be before we alert.

You get a unique URL like:

https://pulsekeeper.io/hb/00000000000000000000000000000000

Sending pings

Call the URL at the end of your job. GET, POST and HEAD all work.

# crontab: run the backup, then report in
0 3 * * * /usr/local/bin/backup.sh && curl -fsS -m 10 --retry 3 https://pulsekeeper.io/hb/00000000000000000000000000000000

To report a failure explicitly, add /fail:

0 3 * * * /usr/local/bin/backup.sh && curl -fsS -m 10 https://pulsekeeper.io/hb/00000000000000000000000000000000 || curl -fsS -m 10 https://pulsekeeper.io/hb/00000000000000000000000000000000/fail

In GitHub Actions or another CI:

- name: Report to PulseKeeper
  if: success()
  run: curl -fsS -m 10 --retry 3 ${{ secrets.PULSEKEEPER_HEARTBEAT_URL }}

How alerts work

  • Nothing is expected before the first ping, so a new heartbeat does not alert.
  • If the next ping does not arrive within the period plus the grace, an incident opens and your channels are alerted.
  • A ping to /fail opens an incident right away.
  • The next successful ping resolves it.
  • If we ourselves could not receive pings for a while, a missed ping in that window does not alert. The deadline moves instead.

A heartbeat URL accepts up to 60 pings a minute. Treat it like a password: anyone who has it can send pings.