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_KEYcrontab
0 3 * * * /usr/local/bin/backup.sh && curl -fsS -m 10 https://codesafe.example/api/v1/ping/9e107d9d372bb6826bd81d3542a419d6Fields
| Field | Type | Required | Limit | What it does |
|---|---|---|---|---|
ping_key | path segment | yes | 32 hex chars | The monitor's key; MONITORS copies the whole URL with COPY PING URL |
Responses
| Status | When | What the client does |
|---|---|---|
204 | codesafe recorded the ping; no body | Nothing |
404 | No active monitor has this key | Check the URL; the monitor may be deactivated or deleted |
503 | codesafe could not record the ping | Retry 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 10fails 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.