docs

Heartbeats

Most alerts tell you something went wrong. A heartbeat tells you something stopped: a backup that no longer runs, a cron job that silently died, a server that went dark. Your job pings a URL every time it runs. If the pings stop, ZapaPUSH alerts you.

Create one

There's nothing to set up in the app: the first ping creates the heartbeat. Give it a name and the interval you expect:

curl -H 'X-ZapaPush-Key: YOUR_KEY' 'https://api.zapapush.com/heartbeat/nightly-backup?every=1d'
  • Name: lowercase letters, digits, -, _ and ., up to 64 characters.
  • every: how often the job runs, from 1m to 7d (90s, 10m, 2h, 1d, or plain seconds). Required on the first ping.
  • grace: optional extra time before it counts as missed. The default is 10% of every, at least a minute and at most an hour (every=1d gets 1 hour).

GET and POST both work, and the key works in the header or in the path: https://api.zapapush.com/heartbeat/nightly-backup/YOUR_KEY.

Ping after your job

Ping only when the job succeeds, so a failing job counts as missed:

0 3 * * * /usr/local/bin/backup.sh && curl -fsS -m 10 -H 'X-ZapaPush-Key: YOUR_KEY' 'https://api.zapapush.com/heartbeat/nightly-backup?every=1d' >/dev/null

From a script:

#!/bin/sh
set -e
pg_dump mydb > /backups/mydb.sql
curl -fsS -m 10 -H "X-ZapaPush-Key: $ZAPAPUSH_KEY" https://api.zapapush.com/heartbeat/pg-dump?every=1d

A server that should just stay up can ping every few minutes:

*/5 * * * * curl -fsS -m 10 -H 'X-ZapaPush-Key: YOUR_KEY' 'https://api.zapapush.com/heartbeat/web-1?every=5m' >/dev/null

When a ping is missed

When every plus grace passes without a ping, you get an alert: Heartbeat missed: nightly-backup. ZapaPUSH checks every minute. The next ping closes the alert on its own, without another push.

List and delete

# All heartbeats for your key, with their last ping
curl -H 'X-ZapaPush-Key: YOUR_KEY' https://api.zapapush.com/heartbeats

# Stop watching one (closes its alert, if any)
curl -X DELETE -H 'X-ZapaPush-Key: YOUR_KEY' https://api.zapapush.com/heartbeat/nightly-backup

To change the interval, ping with a new every (and grace).

Limits

  • Up to 20 heartbeats per key.
  • Pings don't count toward the 60 posts per minute, so a busy key never turns a ping into a false alarm.
  • Pings within 5 seconds of each other count as one.