|
|
- <h1>Pinging API</h1>
- <p>With the Pinging API, you can signal <strong>success</strong>, <strong>fail</strong>, and <strong>start</strong> events from
- your systems.</p>
- <h2>General Notes</h2>
- <p>All ping endpoints support:</p>
- <ul>
- <li>HTTP and HTTPS</li>
- <li>HTTP 1.0, HTTP 1.1 and HTTP 2</li>
- <li>IPv4 and IPv6</li>
- <li>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).</li>
- </ul>
- <p>Successful responses will have the "200 OK" HTTP response status code and a short
- "OK" string in the response body.</p>
- <h2>Send a "success" Signal</h2>
- <div class="highlight"><pre><span></span><code>HEAD|GET|POST PING_ENDPOINT{uuid}
- </code></pre></div>
-
- <p>Signals to SITE_NAME that the job has completed successfully (or,
- continuously running processes are still running and healthy). The <code>uuid</code> parameter
- is unique for each check.</p>
- <p><strong>Example</strong></p>
- <div class="highlight"><pre><span></span><code><span class="nf">GET</span> <span class="nn">/5bf66975-d4c7-4bf5-bcc8-b8d8a82ea278</span> <span class="kr">HTTP</span><span class="o">/</span><span class="m">1.0</span>
- <span class="na">Host</span><span class="o">:</span> <span class="l">hc-ping.com</span>
- </code></pre></div>
-
- <div class="highlight"><pre><span></span><code><span class="kr">HTTP</span><span class="o">/</span><span class="m">1.1</span> <span class="m">200</span> <span class="ne">OK</span>
- <span class="na">Server</span><span class="o">:</span> <span class="l">nginx</span>
- <span class="na">Date</span><span class="o">:</span> <span class="l">Wed, 29 Jan 2020 09:58:23 GMT</span>
- <span class="na">Content-Type</span><span class="o">:</span> <span class="l">text/plain; charset=utf-8</span>
- <span class="na">Content-Length</span><span class="o">:</span> <span class="l">2</span>
- <span class="na">Connection</span><span class="o">:</span> <span class="l">close</span>
- <span class="na">Access-Control-Allow-Origin</span><span class="o">:</span> <span class="l">*</span>
-
- OK
- </code></pre></div>
-
- <h2>Send a "fail" Signal</h2>
- <div class="highlight"><pre><span></span><code>HEAD|GET|POST PING_ENDPOINT{uuid}/fail
- </code></pre></div>
-
- <p>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.</p>
- <p><strong>Example</strong></p>
- <div class="highlight"><pre><span></span><code><span class="nf">GET</span> <span class="nn">/5bf66975-d4c7-4bf5-bcc8-b8d8a82ea278/fail</span> <span class="kr">HTTP</span><span class="o">/</span><span class="m">1.0</span>
- <span class="na">Host</span><span class="o">:</span> <span class="l">hc-ping.com</span>
- </code></pre></div>
-
- <div class="highlight"><pre><span></span><code><span class="kr">HTTP</span><span class="o">/</span><span class="m">1.1</span> <span class="m">200</span> <span class="ne">OK</span>
- <span class="na">Server</span><span class="o">:</span> <span class="l">nginx</span>
- <span class="na">Date</span><span class="o">:</span> <span class="l">Wed, 29 Jan 2020 09:58:23 GMT</span>
- <span class="na">Content-Type</span><span class="o">:</span> <span class="l">text/plain; charset=utf-8</span>
- <span class="na">Content-Length</span><span class="o">:</span> <span class="l">2</span>
- <span class="na">Connection</span><span class="o">:</span> <span class="l">close</span>
- <span class="na">Access-Control-Allow-Origin</span><span class="o">:</span> <span class="l">*</span>
-
- OK
- </code></pre></div>
-
- <h2>Send a "start" Signal</h2>
- <div class="highlight"><pre><span></span><code>HEAD|GET|POST PING_ENDPOINT{uuid}/start
- </code></pre></div>
-
- <p>Sends a "job has started!" message to SITE_NAME. Sending a "start" signal is
- optional, but it enables a few extra features:</p>
- <ul>
- <li>SITE_NAME will measure and display job execution times</li>
- <li>SITE_NAME will detect if the job runs longer than its configured grace time</li>
- </ul>
- <p><strong>Example</strong></p>
- <div class="highlight"><pre><span></span><code><span class="nf">GET</span> <span class="nn">/5bf66975-d4c7-4bf5-bcc8-b8d8a82ea278/start</span> <span class="kr">HTTP</span><span class="o">/</span><span class="m">1.0</span>
- <span class="na">Host</span><span class="o">:</span> <span class="l">hc-ping.com</span>
- </code></pre></div>
-
- <div class="highlight"><pre><span></span><code><span class="kr">HTTP</span><span class="o">/</span><span class="m">1.1</span> <span class="m">200</span> <span class="ne">OK</span>
- <span class="na">Server</span><span class="o">:</span> <span class="l">nginx</span>
- <span class="na">Date</span><span class="o">:</span> <span class="l">Wed, 29 Jan 2020 09:58:23 GMT</span>
- <span class="na">Content-Type</span><span class="o">:</span> <span class="l">text/plain; charset=utf-8</span>
- <span class="na">Content-Length</span><span class="o">:</span> <span class="l">2</span>
- <span class="na">Connection</span><span class="o">:</span> <span class="l">close</span>
- <span class="na">Access-Control-Allow-Origin</span><span class="o">:</span> <span class="l">*</span>
-
- OK
- </code></pre></div>
-
- <h2>Report Script's Exit Status</h2>
- <div class="highlight"><pre><span></span><code>HEAD|GET|POST PING_ENDPOINT{uuid}/{exit-status}
- </code></pre></div>
-
- <p>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.</p>
- <p><strong>Example</strong></p>
- <div class="highlight"><pre><span></span><code><span class="nf">GET</span> <span class="nn">/5bf66975-d4c7-4bf5-bcc8-b8d8a82ea278/1</span> <span class="kr">HTTP</span><span class="o">/</span><span class="m">1.0</span>
- <span class="na">Host</span><span class="o">:</span> <span class="l">hc-ping.com</span>
- </code></pre></div>
-
- <div class="highlight"><pre><span></span><code><span class="kr">HTTP</span><span class="o">/</span><span class="m">1.1</span> <span class="m">200</span> <span class="ne">OK</span>
- <span class="na">Server</span><span class="o">:</span> <span class="l">nginx</span>
- <span class="na">Date</span><span class="o">:</span> <span class="l">Wed, 29 Jan 2020 09:58:23 GMT</span>
- <span class="na">Content-Type</span><span class="o">:</span> <span class="l">text/plain; charset=utf-8</span>
- <span class="na">Content-Length</span><span class="o">:</span> <span class="l">2</span>
- <span class="na">Connection</span><span class="o">:</span> <span class="l">close</span>
- <span class="na">Access-Control-Allow-Origin</span><span class="o">:</span> <span class="l">*</span>
-
- OK
- </code></pre></div>
|
