With the Pinging API, you can signal success, start, and failure events from your systems.
All ping endpoints support:
Successful responses will have the "200 OK" HTTP response status code and a short "OK" string in the response body.
Each Pinging API request needs to uniquely identify a check. SITE_NAME supports two ways of identifying a check: by check's UUID, or by a combination of project's Ping Key and check's slug.
Check's UUID is automatically assigned when the check is created. It is immutable. You cannot replace the automatically assigned UUID with a manually chosen one. When you delete a check, you also lose its UUID and cannot get it back.
You can look up UUIDs of your checks in web UI or via Management API calls.
Check's slug is derived from check's name using Django's slugify function. It applies the following transformations:
For example, if check's name is "Database Backup", its slug is database-backup.
Check's slug can change. SITE_NAME updates check's slug whenever its name changes.
Check's slug is not guaranteed to be unique. If multiple checks in the project have the same name, they also have the same slug. If you make a Pinging API request using a non-unique slug, SITE_NAME will return the "409 Conflict" HTTP status code and ignore the request.
| Endpoint Name | Endpoint Address |
|---|---|
| Success (UUID) | PING_ENDPOINT<uuid> |
| Start (UUID) | PING_ENDPOINT<uuid>/start |
| Failure (UUID) | PING_ENDPOINT<uuid>/fail |
| Report script's exit status (UUID) | PING_ENDPOINT<uuid>/<exit-status> |
| Success (slug) | PING_ENDPOINT<ping-key>/<slug> |
| Start (slug) | PING_ENDPOINT<ping-key>/<slug>/start |
| Failure (slug) | PING_ENDPOINT<ping-key>/<slug>/fail |
| Report script's exit status (slug) | PING_ENDPOINT<ping-key>/<slug>/<exit-status> |
HEAD|GET|POST PING_ENDPOINT<uuid>
Signals to SITE_NAME that the job has completed successfully (or, a continuously running process is still running and healthy).
SITE_NAME identifies the check by the UUID value included in the URL.
Example
GET /5bf66975-d4c7-4bf5-bcc8-b8d8a82ea278 HTTP/1.0
Host: hc-ping.com
HTTP/1.1 200 OK
Server: nginx
Date: Wed, 29 Jan 2020 09:58:23 GMT
Content-Type: text/plain; charset=utf-8
Content-Length: 2
Connection: close
Access-Control-Allow-Origin: *
OK
HEAD|GET|POST PING_ENDPOINT<uuid>/start
Sends a "job has started!" message to SITE_NAME. Sending a "start" signal is optional, but it enables a few extra features:
SITE_NAME identifies the check by the UUID value included in the URL.
Example
GET /5bf66975-d4c7-4bf5-bcc8-b8d8a82ea278/start HTTP/1.0
Host: hc-ping.com
HTTP/1.1 200 OK
Server: nginx
Date: Wed, 29 Jan 2020 09:58:23 GMT
Content-Type: text/plain; charset=utf-8
Content-Length: 2
Connection: close
Access-Control-Allow-Origin: *
OK
HEAD|GET|POST PING_ENDPOINT<uuid>/fail
Signals to SITE_NAME that the job has failed. Actively signaling a failure minimizes the delay from your monitored service failing to you receiving an alert.
SITE_NAME identifies the check by the UUID value included in the URL.
Example
GET /5bf66975-d4c7-4bf5-bcc8-b8d8a82ea278/fail HTTP/1.0
Host: hc-ping.com
HTTP/1.1 200 OK
Server: nginx
Date: Wed, 29 Jan 2020 09:58:23 GMT
Content-Type: text/plain; charset=utf-8
Content-Length: 2
Connection: close
Access-Control-Allow-Origin: *
OK
HEAD|GET|POST PING_ENDPOINT<uuid>/<exit-status>
Sends a success or failure signal depending on the exit status included in the URL. The exit status is a 0-255 integer. SITE_NAME interprets 0 as success and all other values as failure.
SITE_NAME identifies the check by the UUID value included in the URL.
Example
GET /5bf66975-d4c7-4bf5-bcc8-b8d8a82ea278/1 HTTP/1.0
Host: hc-ping.com
HTTP/1.1 200 OK
Server: nginx
Date: Wed, 29 Jan 2020 09:58:23 GMT
Content-Type: text/plain; charset=utf-8
Content-Length: 2
Connection: close
Access-Control-Allow-Origin: *
OK
HEAD|GET|POST PING_ENDPOINT<ping-key>/<slug>
Signals to SITE_NAME that the job has completed successfully (or, a continuously running process is still running and healthy).
SITE_NAME identifies the check by project's ping key and check's slug included in the URL.
Example
GET /fqOOd6-F4MMNuCEnzTU01w/database-backup HTTP/1.0
Host: hc-ping.com
HTTP/1.1 200 OK
Server: nginx
Date: Wed, 29 Jan 2020 09:58:23 GMT
Content-Type: text/plain; charset=utf-8
Content-Length: 2
Connection: close
Access-Control-Allow-Origin: *
OK
HEAD|GET|POST PING_ENDPOINT<ping-key>/<slug>/start
Sends a "job has started!" message to SITE_NAME. Sending a "start" signal is optional, but it enables a few extra features:
SITE_NAME identifies the check by project's ping key and check's slug included in the URL.
Example
GET /fqOOd6-F4MMNuCEnzTU01w/database-backup/start HTTP/1.0
Host: hc-ping.com
HTTP/1.1 200 OK
Server: nginx
Date: Wed, 29 Jan 2020 09:58:23 GMT
Content-Type: text/plain; charset=utf-8
Content-Length: 2
Connection: close
Access-Control-Allow-Origin: *
OK
HEAD|GET|POST PING_ENDPOINT<ping-key/<slug>/fail
Signals to SITE_NAME that the job has failed. Actively signaling a failure minimizes the delay from your monitored service failing to you receiving an alert.
SITE_NAME identifies the check by project's ping key and check's slug included in the URL.
Example
GET /fqOOd6-F4MMNuCEnzTU01w/database-backup/fail HTTP/1.0
Host: hc-ping.com
HTTP/1.1 200 OK
Server: nginx
Date: Wed, 29 Jan 2020 09:58:23 GMT
Content-Type: text/plain; charset=utf-8
Content-Length: 2
Connection: close
Access-Control-Allow-Origin: *
OK
HEAD|GET|POST PING_ENDPOINT<ping-key>/<slug>/<exit-status>
Sends a success or failure signal depending on the exit status included in the URL. The exit status is a 0-255 integer. SITE_NAME interprets 0 as success and all other values as failure.
SITE_NAME identifies the check by project's ping key and check's slug included in the URL.
Example
GET /fqOOd6-F4MMNuCEnzTU01w/database-backup/1 HTTP/1.0
Host: hc-ping.com
HTTP/1.1 200 OK
Server: nginx
Date: Wed, 29 Jan 2020 09:58:23 GMT
Content-Type: text/plain; charset=utf-8
Content-Length: 2
Connection: close
Access-Control-Allow-Origin: *
OK