Heartbeat monitoring (cron jobs and scheduled scripts)

Heartbeat monitoring inverts the model: instead of Everguardly probing your URL on a schedule, your script pings Everguardly when it succeeds. We watch the clock; if the next ping doesn't arrive within the expected interval plus your grace period, we open an incident.

Why it matters for agencies

Most agency operational pain hides in scripts that run unattended: WordPress backup cron at 3 AM, database snapshot script, weekly CSV export to S3, IoT keepalive. "Did it run?" is a question that costs you a phone call from a client when the answer turns out to be no. A heartbeat answers it before the client asks.

The strongest pitch to your client isn't "we monitor your cron job" — it's "we have a paper trail proving your backup ran every night." Pull the ping history off the heartbeat detail page; that's your maintenance plan evidence. Clients who couldn't tell whether they were paying you for actual work suddenly see the line and renew on price increases without argument.

Setup

Create a heartbeat in Dashboard → Heartbeats: name, expected interval (60s up to 1 week), optional grace period (default 60s — tolerates clock skew on shared-hosting cron daemons). We generate a unique 32-character ping URL that looks like:

https://everguardly.com/api/heartbeat/abc23kmnpqrstuvwxyz123456789abcd

Drop that URL into your script at the end of the successful path:

#!/bin/bash
set -e
rsync -a /var/www/ s3://my-backup-bucket/
mysqldump prod | gzip > /backups/$(date +%F).sql.gz
# the heartbeat ping — only runs if everything above succeeded
curl -fsS -o /dev/null --retry 3 https://everguardly.com/api/heartbeat/<slug>

The set -e + the position of the curl after the real work matters: if mysqldump fails, the script exits before the ping fires, and Everguardly notices the missed deadline.

Grace period

Heartbeats have a small jitter tolerance — your daily cron might fire at 03:00:13 today and 03:00:47 tomorrow depending on system load. Set grace to a value comfortable for your runtime: 60s for a 1-minute cron, 300s for an hourly run, 600s for a daily run.

What happens when a ping is missed

We open an incident bound to this heartbeat (visible in Incidents with a Heartbeat source). It fires through your normal alert channels — email, Slack, Discord, webhook — using the same 3-tier routing as monitor alerts (per-heartbeat override → client default → global default). When the next ping finally arrives, the incident auto-resolves and you get the "recovered" alert. The whole thing mirrors monitor incident behavior, so your team's runbooks stay the same.

Common patterns

WordPress backup with UpdraftPlus / WP Time Capsule

Most plugins have a "POST URL on success" hook. Set it to your heartbeat URL — the plugin will fire it automatically after each successful backup.

GitHub Actions nightly job

# .github/workflows/nightly.yml
- name: Heartbeat
  run: curl -fsS https://everguardly.com/api/heartbeat/<slug>
  if: success()

Linux crontab — inline pipe

Use && so a failed command never pings (Everguardly notices the miss):

0 3 * * * /usr/local/bin/backup.sh && curl -fsS https://everguardly.com/api/heartbeat/<slug>

IoT keepalive

Devices behind NAT can still reach the public ping URL. Have your firmware ping once per heartbeat interval.

Rate limit

Each heartbeat URL accepts up to 10 pings per minute. Bursts above that get a 429 + Retry-After header. The cap exists to protect against retry storms; a normal cron ping is one request per cycle, so you'll never hit it.

Pause / resume

Pausing a heartbeat stops the missed-ping check (no incidents) and rejects new pings with a 423 Locked. Resume re-arms the cadence clock from "now" — the user's cron fires its next scheduled run and resumes the green status without a stale miss.

What heartbeats are NOT

Heartbeats are not HTTP uptime monitors — those still belong on Monitors, where Everguardly probes your URL from 3 regions. Heartbeats are for things you can't probe from the outside: cron jobs, background workers, scheduled scripts. The two complement each other.