Heartbeat monitors for cron jobs and scheduled tasks

A heartbeat monitor works the other way round from the other types: instead of FastPing contacting your server, your job contacts FastPing. Each heartbeat monitor has its own secret URL:

https://fastping.app/hb/<token>

1. Your job calls the URL with GET, POST or HEAD each time it finishes successfully. FastPing answers ok.
2. FastPing expects the next call within the monitor's interval, plus the grace period.
3. When that time passes without a call, the monitor goes down and alerts immediately (No ping for 75 min). There is no re-check: the grace period already absorbs normal delays.
4. The next call brings the monitor back up with a recovery alert.

Until the first call arrives, the monitor stays pending (Waiting for the first ping), so a new monitor never alerts before your job has run once. Heartbeats are evaluated once a minute.

Set the interval to how often the job runs, and the grace period to cover how much later than usual a successful run may finish: variations in run time, queueing and clock drift.

Example: a backup starts every night at 03:00 and takes 20 to 40 minutes, then calls the URL. Set the interval to 24 hours and the grace period to 3600 seconds. If last night's run reported at 03:40, tonight's report is due by 04:40; if it has not arrived by then, you are alerted.

The longest interval is 24 hours and the longest grace period is 86400 seconds (24 hours), so jobs that run less often than daily cannot be watched precisely.

Call the URL only when the job succeeded. In a shell, chain the call with &&: it runs only if the job exits with status 0. A job that fails, hangs or never starts then produces no call, and FastPing alerts you.

The URL is the only credential: anyone who knows it can report a heartbeat. Keep it out of public repositories (store it as a secret in CI systems). To change it, create a new heartbeat monitor and delete the old one.

Edit the crontab with crontab -e and append the call to the job's line:

# m  h  dom mon dow  command
30 3 *   *   *    /usr/local/bin/backup.sh && curl -fsS -m 10 --retry 3 -o /dev/null https://fastping.app/hb/<token>

-f makes curl fail on HTTP errors, -sS hides the progress bar but keeps error messages, -m 10 limits the call to 10 seconds and --retry 3 retries on temporary network errors. Cron runs commands with a minimal PATH; use full paths if a command is not found.

With a oneshot service, ExecStartPost= runs only after ExecStart= completed successfully, which is exactly the behaviour you want:

# /etc/systemd/system/backup.service
[Unit]
Description=Nightly backup

[Service]
Type=oneshot
ExecStart=/usr/local/bin/backup.sh
ExecStartPost=/usr/bin/curl -fsS -m 10 --retry 3 -o /dev/null https://fastping.app/hb/<token>

# /etc/systemd/system/backup.timer
[Unit]
Description=Run backup.service every night

[Timer]
OnCalendar=*-*-* 03:30:00
Persistent=true

[Install]
WantedBy=timers.target

Enable it with sudo systemctl daemon-reload && sudo systemctl enable --now backup.timer and check the next run with systemctl list-timers backup.timer. Persistent=true runs a job that was missed while the machine was off as soon as the timer starts again, usually at boot.

Wrap the job in a PowerShell script that reports only when the job succeeded:

# C:\Scripts\backup-and-report.ps1
& 'C:\Scripts\backup.cmd'
if ($LASTEXITCODE -ne 0) { exit $LASTEXITCODE }
Invoke-WebRequest -Uri 'https://fastping.app/hb/<token>' -Method Post -UseBasicParsing -TimeoutSec 10 | Out-Null

Then register a daily task from a Command Prompt opened as administrator:

schtasks /Create /TN "Nightly backup" /SC DAILY /ST 03:30 /RU SYSTEM /TR "powershell.exe -NoProfile -ExecutionPolicy Bypass -File C:\Scripts\backup-and-report.ps1"

You can also create the task in the Task Scheduler window: the action is powershell.exe with the arguments -NoProfile -ExecutionPolicy Bypass -File C:\Scripts\backup-and-report.ps1. Recent versions of Windows also include curl.exe, which you can use instead of Invoke-WebRequest.

Store the heartbeat URL as a repository secret named FASTPING_HEARTBEAT_URL and add a final step that runs only when the previous steps succeeded:

name: Nightly export
on:
  schedule:
    - cron: '30 3 * * *'   # 03:30 UTC
  workflow_dispatch:

jobs:
  export:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v5
      - run: ./scripts/export.sh
      - name: Report success to FastPing
        if: success()
        run: curl -fsS -m 10 --retry 3 -o /dev/null "${{ secrets.FASTPING_HEARTBEAT_URL }}"

Scheduled workflows use UTC and can start late when GitHub Actions is busy, so give the monitor a generous grace period (30 to 60 minutes). GitHub also disables scheduled workflows in public repositories after 60 days without repository activity; the heartbeat alerts you when that happens.

Any HTTP client works. Call the URL as the last step of a successful run:

# Python
import urllib.request
urllib.request.urlopen("https://fastping.app/hb/<token>", timeout=10)

// Node.js 18+
await fetch("https://fastping.app/hb/<token>", { method: "POST", signal: AbortSignal.timeout(10000) });

Heartbeat monitors can also be created with the REST API: the response contains the new monitor's heartbeat_url.