Pings

A ping is how a job says what it is doing. It is the most-used part of Rippler and the only part your servers need to reach.

Ping endpoints take no token. The ping URL contains a secret id, and holding it is the authorisation — a job on some machine should not need your account credentials to say "I ran". Treat the URL as a secret; anyone with it can report runs for that monitor.

The four URLs

Every monitor has a pingID. All four paths are built from it:

The shortest useful integration is one call to the base URL when the job finishes. Adding /start/ before the work buys two things: a duration, and a failure reported the moment it happens rather than when the next ping fails to arrive.

curl -fsS -m 10 --retry 5 -o /dev/null "https://api.rippler.io/ping/<pingID>/start/"
if /path/to/your-job.sh; then
	curl -fsS -m 10 --retry 5 -o /dev/null "https://api.rippler.io/ping/<pingID>/"
else
	curl -fsS -m 10 --retry 5 -o /dev/null "https://api.rippler.io/ping/<pingID>/fail/"
fi

Any HTTP method works. curl defaults to GET, which is why every example here is a bare curl.

Parameters

Both are optional, and both go on the query string.

?rid= — run id

Ties a closing ping to its own opening one, instead of to whatever event happened to come last.

/ping/<pingID>/start/?rid=a1b2c3
/ping/<pingID>/?rid=a1b2c3&duration=12.5

Without it, a closing ping pairs with the previous event. For a job that runs every minute and occasionally takes three, the starts and ends interleave and the durations come out wrong. With a run id they cannot.

Up to 64 characters of letters, digits, ., _, : and -. In a shell, $$ (the process id) is a reasonable one, and it is what the app's crontab snippet uses.

?duration= — run time in seconds

What the job measured, which is better than what the server can infer. The server only sees when the pings arrived, which includes network time and any retry backoff.

Accepts up to 31 days. Longer than that is a mistake rather than a job.

A bad parameter is dropped, never rejected

This endpoint is public and unauthenticated, and it is called from the middle of other people's jobs. So a malformed extra is discarded and the ping still counts:

• A bad duration falls back to the server's own measurement.
• A bad rid falls back to pairing with the previous event.

A job must never fail to report itself because it sent a bad extra.

Trailing slashes

Every path ends in one. Without it you get a 308 redirect — harmless for a GET, but a POST body will not survive it. Send /ping/<pingID>/start/, not /ping/<pingID>/start.

Responses

The same envelope as the rest of the API:

{ "success": true, "data": { ... } }

An unknown pingID returns success: false with a Monitor not found message rather than an error status, so a job wrapper that only checks the HTTP code is not tricked into failing.

Rate limits

120 requests per minute per IP, shared with the rest of the API. Over that you get a 429.

Machine-readable reference

The generated ping reference is produced from the same schemas the endpoints validate against, so it cannot drift from what is enforced.