Skip to main content
A heartbeat watches something that is supposed to happen regularly. The thing being watched calls a URL when it finishes; nothing arriving is the signal. This is the only way to notice work that has quietly stopped. A nightly backup script that no longer runs produces no failure, no output and no error, and is indistinguishable from one that is running fine.

​
Setting one up

Give it a name, say how often it runs, and say how long after that you want to be told. The second number is grace. A run that takes a while, or a machine whose clock has drifted, should not raise an alert — so a job that runs hourly with fifteen minutes of grace is late at seventy-five minutes, not at sixty-one. Shipways gives you an address. Call it at the end of the work, not the start: the point is to hear that it finished.
&& rather than ;, so a failed job does not report success. Both GET and POST are accepted, because the way these lines actually get written is with curl.

​
It does not have to be a Shipways job

Anything that can make an HTTP call when it finishes can be watched: a job on a machine Shipways does not manage, a GitHub Action, a partner’s nightly import. Heartbeats are deliberately not tied to scheduled jobs.

​
Missing one

A heartbeat whose deadline passes opens an alert. A heartbeat that has never been called has no deadline to miss, and shows as waiting for its first call rather than as late. Set one up, then run the job once by hand to confirm the address is right.

​
Removing one

The address stops answering, so whatever was calling it needs changing too — a curl to a dead heartbeat with -f will start failing the job it was appended to.