Using Alwaysbeat

Signaling jobs

How your job tells Alwaysbeat what happened: success, start, failure, or an exit code. Every signal is a plain HTTP request to the check's ping URL.

The ping URL

Each check has a base URL containing its unique ID:

https://ping.alwaysbeat.com/ping/<check-uuid>

Requests can use any HTTP method (GET, POST, HEAD) and need no body or headers. A valid ping returns 200 OK with the body ok. An unknown or malformed check ID returns 404. Alwaysbeat never rejects a valid ping, so a bare GET is the normal, expected case.

Success ping

Send a request to the base URL to report that the job finished successfully. This sets the check to up and schedules the next deadline.

curl -fsS https://ping.alwaysbeat.com/ping/<uuid>

Start ping

Send a request to the /start sub-path when the job begins. This records the start time but does not change the check's status. When the matching success or failure ping arrives, Alwaysbeat records the elapsed time as the run's duration — which powers the run-duration chart and the "ran too long" control (see Reliability controls).

curl -fsS https://ping.alwaysbeat.com/ping/<uuid>/start
# ... job runs ...
curl -fsS https://ping.alwaysbeat.com/ping/<uuid>

Failure ping

Send a request to the /fail sub-path to actively report a failure. This flips the check to down immediately, rather than waiting for a ping to go missing — so you're alerted the moment your job knows it failed.

curl -fsS https://ping.alwaysbeat.com/ping/<uuid>/fail

Exit-status ping

Append a command's exit code to report success or failure in one call. This is the most convenient form for shell and cron: 0 is treated as success, any non-zero value (1–255) as a failure.

# run the command, then report whatever it exited with
/usr/local/bin/backup.sh
curl -fsS https://ping.alwaysbeat.com/ping/<uuid>/$?

The reported exit code is stored and shown against the event in the dashboard, which makes after-the-fact debugging easier.

Common patterns

Cron

# ping only on success
0 3 * * *  backup.sh && curl -fsS --retry 3 https://ping.alwaysbeat.com/ping/<uuid>

Shell wrapper (report start, then success or failure)

URL=https://ping.alwaysbeat.com/ping/<uuid>
curl -fsS "$URL/start"
if backup.sh; then
  curl -fsS "$URL"
else
  curl -fsS "$URL/fail"
fi

Python

import urllib.request
URL = "https://ping.alwaysbeat.com/ping/<uuid>"

urllib.request.urlopen(URL + "/start", timeout=10)
try:
    do_work()
    urllib.request.urlopen(URL, timeout=10)        # success
except Exception:
    urllib.request.urlopen(URL + "/fail", timeout=10)  # failure
    raise