Pings

A ping is how a job reports what it is doing. It is the only part of Rippler your servers need to reach.

Ping endpoints take no token. The ping URL contains a secret id, and holding it is the authorisation, so a job does not need your account credentials. Treat the URL as a secret. Anyone with it can report runs for that monitor.

Report a run

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

The simplest integration is one call to the base URL when the job finishes. Adding /start/ before the work gives two things: a duration, and a failure reported when it happens instead of 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, so every example here is a bare curl.

Parameters

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

?rid=: run id

Pairs a closing ping with its own opening one instead of the previous event.

/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. A run id prevents that.

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

?duration=: run time in seconds

The run time as the job measured it. Prefer it over the server's own measurement, which only sees when the pings arrived and includes network time and any retry backoff.

Accepts up to 31 days.

Invalid parameters do not reject a ping

This endpoint is called from inside other people's jobs, so a malformed parameter 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.

Trailing slashes

Every path ends in one. Without it you get a 308 redirect. That is harmless for a GET, but a POST body does 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 and a 200 status, so a job wrapper that only checks the HTTP code does not fail.

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.