Signaling failures

You can actively signal a failure to Healthchecks.io by slightly changing the ping URL: append either /fail or /{exit-status} to your normal ping URL. The exit status should be a 0-255 integer. Healthchecks.io will interpret exit status 0 as success and all non-zero values as failures.

Examples:

# Reports failure by appending the /fail suffix:
curl --retry 3 https://hc-ping.com/your-uuid-here/fail

# Reports failure by appending a non-zero exit status:
curl --retry 3 https://hc-ping.com/your-uuid-here/1

By actively signaling failures to Healthchecks.io, you can minimize the delay from your monitored service encountering a problem to you getting notified about it.

Alternatively, if using different URLs for success and failure signals is not feasible, you can configure Healthchecks.io to classify HTTP pings as success or failure signals by looking for specific keywords in the HTTP request body.

Shell Scripts

The below shell script appends $? (a special variable that contains the exit status of the last executed command) to the ping URL:

#!/bin/sh

/usr/bin/certbot renew
curl --retry 3 https://hc-ping.com/your-uuid-here/$?

Python

Below is a skeleton code example in Python which signals a failure when the work function returns an unexpected value or throws an exception:

import requests
URL = "https://hc-ping.com/your-uuid-here"

def do_work():
    # Do your number crunching, backup dumping, newsletter sending work here.
    # Return a truthy value on success.
    # Return a falsy value or throw an exception on failure.
    return True

success = False
try:
    success = do_work()
finally:
    # On success, requests https://hc-ping.com/your-uuid-here
    # On failure, requests https://hc-ping.com/your-uuid-here/fail
    requests.get(URL if success else URL + "/fail")