DOCUMENTATION

Ping

A cron job's heartbeat for a dead-man's switch.

A scheduled job calls its monitor's ping URL at the end of each run; when the ping stays away, codesafe alerts the project's recipients.

Request

GET /api/v1/ping/<ping_key>

No body and no header: the ping_key in the path is the credential. POST works the same way.

Example

curl

curl -fsS -m 10 https://codesafe.example/api/v1/ping/$PING_KEY

crontab

0 3 * * * /usr/local/bin/backup.sh && curl -fsS -m 10 https://codesafe.example/api/v1/ping/9e107d9d372bb6826bd81d3542a419d6

Fields

FieldTypeRequiredLimitWhat it does
ping_keypath segmentyes32 hex charsThe monitor's key; MONITORS copies the whole URL with COPY PING URL

Responses

StatusWhenWhat the client does
204codesafe recorded the ping; no bodyNothing
404No active monitor has this keyCheck the URL; the monitor may be deactivated or deleted
503codesafe could not record the pingRetry once a few seconds later: a lost ping reads as a late job

Notes

  • Ping after the job succeeds, job && curl …: a failed run then sends no ping and the monitor turns LATE.
  • A monitor is LATE when its last ping is older than its period plus its grace (15 minutes by default), and alerts the project's mail and chat recipients; it alerts again at most every 6 hours.
  • Between the period and the grace, MONITORS shows the monitor as DUE.
  • A monitor that has never pinged counts from its creation.
  • -fsS -m 10 fails on an error status, stays quiet otherwise, and stops after 10 seconds: a ping never holds up the job.
Methods, bodies and repeats

Any method records the ping, and a body is ignored. A repeated ping records the newer time and is always safe to resend. The ping takes no api_key and spends no project budget.

Setting a monitor up

In MONITORS, create a monitor with a name, its project, how often the job runs (expected every, in minutes) and its grace. Its ping URL is ready once it is saved; copy it from the row.