Signaling failures

You can actively signal a failure to Healthchecks 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 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://healthchecks.niyawe.de/ping/your-uuid-here/fail

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

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

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://healthchecks.niyawe.de/ping/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://healthchecks.niyawe.de/ping/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://healthchecks.niyawe.de/ping/your-uuid-here
    # On failure, requests https://healthchecks.niyawe.de/ping/your-uuid-here/fail
    requests.get(URL if success else URL + "/fail")