# Pinging API With the Pinging API, you can signal **success**, **start**, and **failure** events from your systems. ## General Notes All ping endpoints support: * HTTP and HTTPS * HTTP 1.0, HTTP 1.1 and HTTP 2 * IPv4 and IPv6 * HEAD, GET, and POST requests methods. The HTTP POST requests can optionally include diagnostic information in the request body. If the request body looks like a UTF-8 string, SITE_NAME stores the request body (limited to the first 10KB for each received ping). Successful responses will have the "200 OK" HTTP response status code and a short "OK" string in the response body. ## UUIDs and Slugs 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](../api/) calls. **Check's slug** is derived from check's name using Django's [slugify](https://docs.djangoproject.com/en/3.2/ref/utils/#django.utils.text.slugify) function. It applies the following transformations: * Convert to ASCII. * Convert to lowercase. * Remove characters that aren't alphanumerics, underscores, hyphens, or whitespace. * Replace any whitespace or repeated hyphens with single hyphens. * Remove leading and trailing whitespace, hyphens, and underscores. 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. ## Endpoints Endpoint Name | Endpoint Address ------------------------------------------------------------|------- [Success (UUID)](#success-uuid) | `PING_ENDPOINT` [Start (UUID)](#start-uuid) | `PING_ENDPOINT/start` [Failure (UUID)](#fail-uuid) | `PING_ENDPOINT/fail` [Report script's exit status (UUID)](#exitcode-uuid) | `PING_ENDPOINT/` [Success (slug)](#success-slug) | `PING_ENDPOINT/` [Start (slug)](#start-slug) | `PING_ENDPOINT//start` [Failure (slug)](#fail-slug) | `PING_ENDPOINT//fail` [Report script's exit status (slug)](#exitcode-slug) | `PING_ENDPOINT//` ## Send a "success" Signal Using UUID {: #success-uuid .rule } ```text HEAD|GET|POST PING_ENDPOINT ``` 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. ### Response Codes 200 OK : The request succeeded. 404 not found : Could not find a check with the specified UUID. **Example** ```http GET /5bf66975-d4c7-4bf5-bcc8-b8d8a82ea278 HTTP/1.0 Host: hc-ping.com ``` ```http 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 ``` ## Send a "start" Signal Using UUID {: #start-uuid .rule } ```text HEAD|GET|POST PING_ENDPOINT/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 will measure and display job execution times * SITE_NAME will detect if the job runs longer than its configured grace time SITE_NAME identifies the check by the UUID value included in the URL. ### Response Codes 200 OK : The request succeeded. 404 not found : Could not find a check with the specified UUID. **Example** ```http GET /5bf66975-d4c7-4bf5-bcc8-b8d8a82ea278/start HTTP/1.0 Host: hc-ping.com ``` ```http 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 ``` ## Send a "failure" Signal Using UUID {: #fail-uuid .rule } ```text HEAD|GET|POST PING_ENDPOINT/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. ### Response Codes 200 OK : The request succeeded. 404 not found : Could not find a check with the specified UUID. **Example** ```http GET /5bf66975-d4c7-4bf5-bcc8-b8d8a82ea278/fail HTTP/1.0 Host: hc-ping.com ``` ```http 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 ``` ## Report Script's Exit Status (Using UUID) {: #exitcode-uuid .rule } ```text HEAD|GET|POST PING_ENDPOINT/ ``` 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. ### Response Codes 200 OK : The request succeeded. 400 invalid url format : The URL does not match the expected format. 404 not found : Could not find a check with the specified UUID. **Example** ```http GET /5bf66975-d4c7-4bf5-bcc8-b8d8a82ea278/1 HTTP/1.0 Host: hc-ping.com ``` ```http 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 ``` ## Send a "success" Signal (Using Slug) {: #success-slug .rule } ```text HEAD|GET|POST PING_ENDPOINT/ ``` 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. ### Response Codes 200 OK : The request succeeded. 404 not found : Could not find a check with the specified ping key and slug combination. 409 ambiguous slug : Ambiguous, the slug matched multiple checks. **Example** ```http GET /fqOOd6-F4MMNuCEnzTU01w/database-backup HTTP/1.0 Host: hc-ping.com ``` ```http 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 ``` ## Send a "start" Signal (Using Slug) {: #start-slug .rule } ```text HEAD|GET|POST PING_ENDPOINT//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 will measure and display job execution times * SITE_NAME will detect if the job runs longer than its configured grace time SITE_NAME identifies the check by project's ping key and check's slug included in the URL. ### Response Codes 200 OK : The request succeeded. 404 not found : Could not find a check with the specified ping key and slug combination. 409 ambiguous slug : Ambiguous, the slug matched multiple checks. **Example** ```http GET /fqOOd6-F4MMNuCEnzTU01w/database-backup/start HTTP/1.0 Host: hc-ping.com ``` ```http 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 ``` ## Send a "failure" Signal (Using slug) {: #fail-slug .rule } ```text HEAD|GET|POST PING_ENDPOINT/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. ### Response Codes 200 OK : The request succeeded. 404 not found : Could not find a check with the specified ping key and slug combination. 409 ambiguous slug : Ambiguous, the slug matched multiple checks. **Example** ```http GET /fqOOd6-F4MMNuCEnzTU01w/database-backup/fail HTTP/1.0 Host: hc-ping.com ``` ```http 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 ``` ## Report Script's Exit Status (Using Slug) {: #exitcode-slug .rule } ```text HEAD|GET|POST PING_ENDPOINT// ``` 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. ### Response Codes 200 OK : The request succeeded. 400 invalid url format : The URL does not match the expected format. 404 not found : Could not find a check with the specified ping key and slug combination. 409 ambiguous slug : Ambiguous, the slug matched multiple checks. **Example** ```http GET /fqOOd6-F4MMNuCEnzTU01w/database-backup/1 HTTP/1.0 Host: hc-ping.com ``` ```http 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 ```