5.4Ping endpoints
Send a POST, GET or HEAD request to one of these URLs. No body, API key or login is needed.
| Request | Meaning | Result |
|---|---|---|
https://<your-ping-url> | The run finished and succeeded. | Up. |
https://<your-ping-url>/start | The run has started. | No result yet. The finish ping then reports the run's duration. |
https://<your-ping-url>/fail | The run finished and failed. | Down, with job reported failure. |
https://<your-ping-url>/0 | The run exited with code 0. | Up, the same as a success ping. |
https://<your-ping-url>/1 to /255 | The run exited with this code. | Down, with job exited with code <N>. |
An exit code is the number a program returns when it ends. 0 means success, anything else means failure. In a shell, $? holds the exit code of the last command. Send it as a plain number from 0 to 255, such as /7. Forms such as /07, /+1 or /256 are refused.
Without /start, the response time of a result is 0.
Responses#
| Status and body | Meaning | What to do |
|---|---|---|
204 (empty) | The ping was accepted. | Nothing. |
400 missing token | The URL ends at /heartbeat/. | Copy the full ping URL from the monitor page. |
404 unknown token | No monitor has this token. | Check the URL. The monitor may have been deleted. |
404 unknown action: use /start, /fail or an exit code | The part after the token is wrong. | Use /start, /fail or a number from 0 to 255. |
404 page not found | The URL is not a ping URL. | Copy the URL again from the monitor page. |
405 method not allowed | The method is not POST, GET or HEAD. | Use POST or GET. |
429 rate limit exceeded | Too many pings in a short time. | Wait 60 seconds (the Retry-After header), then try again. |
500 internal error | A problem on obsrvly's side. | Retry. curl --retry 3 does this for you. |
Limits#
Each ping URL accepts up to 60 pings a minute, with short bursts of up to 10. One run needs one or two pings. Do not ping in a tight loop.
Test your ping#
The send test ping button in the form stays disabled for heartbeat monitors. Test from a terminal instead.
curl -i -X POST "https://<your-ping-url>"The first line of the answer should show status 204. The monitor page then shows an up result and a new Last check time. To test without the details, use curl -fsS -m 10 --retry 3 "https://<your-ping-url>". It prints nothing when the ping works, and an error when it does not.