Heartbeat ping

Report that a scheduled job ran: the ping endpoint, its optional JSON body, every response and the limits.

Last reviewed Nov 6, 2026

On this page

A heartbeat is a monitor for a job that has no URL to check, such as a backup or a scheduled task. The job calls its ping URL when it runs, and OctoPing alerts when a ping doesn't arrive in time. This page is the reference for that call. The settings that decide when a ping is late are on the checks page.

Find the ping URL

Create a heartbeat under Heartbeats, then open it. The Ping URL card shows the full address and a cURL command to test it. Until the first ping arrives, Recent Pings shows a ready crontab line for the heartbeat's interval. The last part of the address is the heartbeat's secret key. Anyone who has it can send pings for that heartbeat, so keep it out of public repositories.

The endpoint

The endpoint accepts GET and POST. A POST can carry a JSON body. A GET can't.

GEThttps://octoping.com/api/ping/{secret_key}

Receive Heartbeat Ping

secret_key (path, string, required)

POSThttps://octoping.com/api/ping/{secret_key}

Receive Heartbeat Ping

secret_key (path, string, required)

Neither needs authentication. The secret_key in the path selects the heartbeat. The request needs no headers.

Request body

A POST may send a JSON body of up to 10240 bytes. OctoPing stores it with the ping, and it appears under Recent Pings on the heartbeat's page. Use it to report something about the run, such as how long it took or how many rows it processed. A body that isn't valid JSON is ignored, and the ping still counts. A body over the limit is refused and the ping isn't recorded.

Response

A response is JSON with these keys.

Key	Type	Meaning
`ok`	boolean	True when the ping was recorded.
`message`	string	A short description of the outcome. The table below lists them.
`heartbeat_id`	string or null	The heartbeat's id. Null when the secret key matches no heartbeat.
`received_at`	string or null	When OctoPing recorded the ping, as a UTC ISO 8601 timestamp. Null when ok is false.

These outcomes all return HTTP 200. Check ok in the body to see whether the ping was recorded.

ok	message	What happened
true	Ping received	The ping was recorded.
false	Invalid ping URL	No heartbeat has this secret key.
false	Heartbeat monitor is disabled	The heartbeat is switched off. Nothing was recorded.
false	Too many pings. Please try again later.	This heartbeat is receiving pings too often.
false	Payload too large	The body was over 10240 bytes.

Limits

Each heartbeat accepts only so many pings in a short time, and each address can only send so many requests. A ping over the heartbeat's limit returns ok false with the message above. A request over the address limit returns HTTP 429 with a detail message. The address limit is shared by every heartbeat that pings from the same address, so a host that runs many frequent jobs can reach it.

What a ping does

It records the ping with its time, source address, user agent and any JSON body.
It sets the heartbeat's last ping time, which moves the deadline for the next one.
If the heartbeat was unhealthy, it becomes healthy again and the recovery alert goes out under the rules on the alert rules page.

Examples

Ping from a shell.

bash

curl -fsS https://octoping.com/api/ping/YOUR_SECRET_KEY

Send a JSON body with a POST.

bash

curl -fsS -X POST \
  -H "Content-Type: application/json" \
  -d '{"job":"nightly-backup","rows":1204}' \
  https://octoping.com/api/ping/YOUR_SECRET_KEY

Ping only when the job succeeds, so a failed run goes quiet and the heartbeat alerts.

bash

./backup.sh && curl -fsS https://octoping.com/api/ping/YOUR_SECRET_KEY > /dev/null

A recorded ping returns a body like this. The id and time are examples.

json

{
  "ok": true,
  "message": "Ping received",
  "heartbeat_id": "00000000-0000-0000-0000-000000000000",
  "received_at": "2026-01-15T03:00:02.418Z"
}

Heartbeat ping

Related