Send heartbeats from a scheduled job

• A connected agent with the Monitor write permission.
• A job that can make one outbound HTTPS request with curl, wget or any HTTP client.

1. 1

   Step 1. Ask your agent for a heartbeat monitor. Give it the expected interval and a grace period.

   Prompt text

   Copy

   Create a heartbeat monitor named nightly-backup. It runs every day. Use a one hour grace period. Show me the heartbeat token.

2. 2

   Step 2. Store the token from the response as a secret, for example POSTDEPLOY_HEARTBEAT_TOKEN. It starts with hb_ and PostDeploy shows it once.

Send start before the job and the exit code after it, so a failed job records fail. GET and POST behave the same. The token in the URL is the only authentication, so treat the URL as a secret. No header is needed.

curl -fsS "https://ingest.postdeploy.dev/h/$POSTDEPLOY_HEARTBEAT_TOKEN?state=start"
/usr/local/bin/nightly-backup.sh
curl -fsS "https://ingest.postdeploy.dev/h/$POSTDEPLOY_HEARTBEAT_TOKEN/$?"

state=start

Marks the run as started. It records no check.

state=finish, or no state

Records an Up check. An open incident resolves after two passes in a row.

state=fail

Records a Down check, opens an incident at once, and notifies your alert channels.

Append the exit code to the URL. 0 records finish. Any other value records fail. The exit code wins over a state parameter.

0 2 * * * /usr/local/bin/nightly-backup.sh; curl -fsS "https://ingest.postdeploy.dev/h/$POSTDEPLOY_HEARTBEAT_TOKEN/$?" > /dev/null

Add a ping_id when your job retries the request. PostDeploy records one check per ping_id for 24 hours and answers 202 to each duplicate. Use one value per run, not per request.

curl -fsS --retry 3 "https://ingest.postdeploy.dev/h/$POSTDEPLOY_HEARTBEAT_TOKEN/0?ping_id=nightly-$(date +%F)"

A ping_id has 1 to 128 characters: letters, digits, _, . and -.

A received fail is detected at once, because your job reports it. A run that never starts sends nothing, so nothing is detected. Report fail from the job wrapper wherever the job can fail, and use a separate watchdog if a missed run must alert someone.

1. 1

   Step 1. Send one ping and read the status line.

   Terminal shell

   Copy

   curl -i "https://ingest.postdeploy.dev/h/$POSTDEPLOY_HEARTBEAT_TOKEN"
   # Expect: HTTP/1.1 202 Accepted

2. 2

   Step 2. Open Monitor. The monitor row shows a check time. Its detail screen lists the ping under "Recent checks" as Up.

3. 3

   Step 3. Send /1 once to test failure. The detail screen shows a Down check and an open incident. Send two passes to resolve it.

A job stopped and no alert arrived

A missing ping is not detected. Send an explicit fail from the job. After the first check, watch for Late on the Monitor screen.

A retried ping adds no check

The same ping_id within 24 hours is a duplicate. Use one ping_id per run.

The monitor shows Up but the incident is still open

An incident resolves after two passes in a row. Wait for the next successful run.

The URL returns 404

The token is unknown or was reissued. Ask your agent to reissue the token and approve the request in the dashboard.

Pings return 202 but record nothing

The monitor is paused or the subscription is inactive. Ask your agent to resume the monitor.