Shell Scripts

You can easily add Healthchecks monitoring to a shell script. All you have to do is make an HTTP request at an appropriate place in the script. curl and wget are two common command-line HTTP clients you can use.

# Sends an HTTP GET request with curl:
curl -m 10 --retry 5 https://hc.oceanx.org/ping/your-uuid-here

# Silent version (no stdout/stderr output unless curl hits an error):
curl -fsS -m 10 --retry 5 -o /dev/null https://hc.oceanx.org/ping/your-uuid-here

Here's what each curl parameter does:

-m <seconds>

Maximum time in seconds that you allow the whole operation to take.

--retry <num>

If an HTTP request fails, retry up to this many times. By default, curl uses an increasing delay between each retry (1s, 2s, 4s, 8s, ...). See also --retry-delay.

-f, --fail

Makes curl treat non-200 responses as errors.

-s, --silent

Silent or quiet mode. Hides the progress meter, but also hides error messages.

-S, --show-error

Re-enables error messages when -s is used.

-o /dev/null

Redirect curl's stdout to /dev/null (error messages still go to stderr).

Signaling Failure from Shell Scripts

You can append /fail or /{exit-status} to any ping URL and use the resulting URL to actively signal a failure. The exit status should be a 0-255 integer. Healthchecks will interpret exit status 0 as success and all non-zero values as failures.

The following example runs /usr/bin/certbot renew, and uses the $? variable to look up its exit status:

#!/bin/sh

# Payload here:
/usr/bin/certbot renew
# Ping Healthchecks
curl -m 10 --retry 5 https://hc.oceanx.org/ping/your-uuid-here/$?

Logging Command Output

When pinging with HTTP POST, you can put extra diagnostic information in the request body. If the request body looks like a valid UTF-8 string, Healthchecks will accept and store the first 10KB of the request body.

In the below example, certbot's output is captured and submitted via HTTP POST:

#!/bin/sh

m=$(/usr/bin/certbot renew 2>&1)
curl -fsS -m 10 --retry 5 --data-raw "$m" https://hc.oceanx.org/ping/your-uuid-here

Auto-provisioning New Checks

This example uses Healthchecks Management API to create a check "on the fly" (if it does not already exist) and retrieve its ping URL. Using this technique, you can write services that automatically register with Healthchecks the first time they run.

#!/bin/bash

API_KEY=your-api-key-here

# Check's parameters. This example uses system's hostname for check's name.
PAYLOAD='{"name": "'`hostname`'", "timeout": 60, "grace": 60, "unique": ["name"]}'

# Create the check if it does not exist.
# Grab the ping_url from JSON response using the jq utility:
URL=`curl -s https://hc.oceanx.org/api/v1/checks/  -H "X-Api-Key: $API_KEY" -d "$PAYLOAD"  | jq -r .ping_url`

# Finally, send a ping:
curl -m 10 --retry 5 $URL