Skip to content
Knowledge base

Monitor Backrest backups with a heartbeat

Backrest can call a Healthchecks-style URL on every backup. A RealUptime heartbeat answers the same start, success and fail requests, so a missed or failed plan becomes an alert.

1. Create the heartbeat

Add a monitor with Check type Heartbeat (cron), set the interval to the plan's schedule and the grace to how long a backup can take, and copy the ping URL. One heartbeat per Backrest plan keeps each plan's alert separate. Heartbeats are on every plan, Free included.

2. Add a Healthchecks hook to the plan

In Backrest, edit the plan, add a hook, choose the Healthchecks type and paste the ping URL. Select the conditions CONDITION_SNAPSHOT_START, CONDITION_SNAPSHOT_SUCCESS and CONDITION_SNAPSHOT_ERROR. Backrest's documentation says this hook appends /start for start events and /fail for error events and requests the plain URL on success, sending its summary as the POST body: the three requests a RealUptime ping URL answers, with the summary kept as the failure detail.

3. Or use a command hook

If you would rather call it yourself, add a Command hook on CONDITION_SNAPSHOT_SUCCESS that runs curl -fsS -m 10 "$PING_URL", and one on CONDITION_SNAPSHOT_ERROR that runs curl -fsS -m 10 --data-raw {{ .ShellEscape .Error }} "$PING_URL/fail". Set the hooks' error behaviour to ignore, so a network blip on the ping never cancels a backup.

4. Why the heartbeat still matters with hooks

A hook only runs when Backrest runs. If the Backrest container stops, the host is off, or the schedule is disabled, there is no error event to send. The heartbeat notices the success ping that never came, which is the failure hooks alone cannot report.

Go deeper

The full reference lives in the docs: Heartbeat monitors documentation. Error codes named above are each explained in the error-code reference.