Healthchecks.io

https://healthchecks.io/docs
Admin
Healthchecks.io is a service monitoring platform that tracks the health and status of cron jobs,...
Tokens:73,157
Snippets:608
Trust Score:9.9
Update:1 month ago
Show doc for...
Tokens:
Raw
### Start signal request and response example

Source: https://healthchecks.io/docs/http_api

A complete example of a GET request to initiate a start signal and the corresponding HTTP 200 OK response from the server.

```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: *
Ping-Body-Limit: 100000

OK
```

--------------------------------

### Start signal request and response example

Source: https://healthchecks.io/docs/http_api

An example of a GET request to signal the start of a job and the corresponding HTTP 200 OK response.

```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: *
Ping-Body-Limit: 100000

OK
```

--------------------------------

### Set start signal keywords

Source: https://healthchecks.io/docs/api

Example of configuring start signal keywords with subject filtering enabled.

```json
{"filter_subject": true, "start_kw": "STARTED"}
```

--------------------------------

### Start Docker containers

Source: https://healthchecks.io/docs/self_hosted_docker

Navigate to the docker directory and start the services defined in the configuration.

```bash
$ cd docker
$ docker compose up
```

--------------------------------

### Install Python requirements

Source: https://healthchecks.io/docs/self_hosted

Install the necessary Python dependencies into the virtual environment.

```bash
$ pip install wheel
$ pip install -r healthchecks/requirements.txt
```

--------------------------------

### Success signal request and response example

Source: https://healthchecks.io/docs/http_api

An example of a GET request to signal success and the corresponding HTTP response from the server.

```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: *
Ping-Body-Limit: 100000

OK
```

--------------------------------

### Install apprise package

Source: https://healthchecks.io/docs/self_hosted_configuration

Installs the apprise package required to enable the Apprise integration.

```bash
pip install apprise
```

--------------------------------

### Setup virtual environment

Source: https://healthchecks.io/docs/self_hosted

Create and activate a Python virtual environment for the project.

```bash
$ python3 -m venv hc-venv
$ source hc-venv/bin/activate
```

--------------------------------

### Success Signal Request and Response Example

Source: https://healthchecks.io/docs/http_api

An example of a GET request to a specific UUID and the corresponding HTTP 200 OK response from the server.

```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: *
Ping-Body-Limit: 100000

OK
```

--------------------------------

### Run project tests

Source: https://healthchecks.io/docs/self_hosted

Execute the test suite to verify the installation.

```bash
$ ./manage.py test
```

--------------------------------

### Failure signal request and response example

Source: https://healthchecks.io/docs/http_api

An example of a GET request to signal failure and the corresponding HTTP response from the server.

```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: *
Ping-Body-Limit: 100000

OK
```

--------------------------------

### Install system dependencies

Source: https://healthchecks.io/docs/self_hosted

Install required system packages including gcc, python3-dev, and python3-venv on a Debian-based OS.

```bash
$ sudo apt-get update
$ sudo apt-get install -y gcc python3-dev python3-venv
```

--------------------------------

### Failure Signal Request and Response Example

Source: https://healthchecks.io/docs/http_api

An example of a GET request to signal failure and the corresponding 200 OK response from the server.

```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: *
Ping-Body-Limit: 100000

OK
```

--------------------------------

### GET|HEAD|POST /<ping-key>/<slug>/start

Source: https://healthchecks.io/docs/http_api

Sends a start signal to Healthchecks.io for a check identified by ping-key and slug. This indicates that the job has started.

```APIDOC
## [GET|HEAD|POST] /<ping-key>/<slug>/start

### Description
Sends a start signal to Healthchecks.io for a check identified by ping-key and slug. This indicates that the job has started.

### Method
GET, HEAD, POST

### Endpoint
https://hc-ping.com/<ping-key>/<slug>/start

### Response
#### Success Response (200 OK)
The request succeeded.

#### Success Response (200 OK, not found)
Could not find a check with the specified ping-key and slug.

#### Success Response (200 OK, rate limited)
Rate limit exceeded, request was ignored. Please do not ping a single check more than 5 times per minute.

#### Error Response (400 invalid url format)
The URL does not match the expected format.
```

--------------------------------

### Report Script Exit Status Example

Source: https://healthchecks.io/docs/http_api

An example of a GET request to report a failure status (1) for a specific check UUID, followed by the corresponding HTTP response.

```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: *
Ping-Body-Limit: 100000

OK
```

--------------------------------

### Assign all integrations

Source: https://healthchecks.io/docs/api

Example of assigning all existing integrations using the wildcard character.

```json
{"channels": "*"}
```

--------------------------------

### Set tags

Source: https://healthchecks.io/docs/api

Example of providing a space-delimited list of tags.

```json
{"tags": "reports staging"}
```

--------------------------------

### Configure integration channels

Source: https://healthchecks.io/docs/api

Examples of assigning all integrations, unassigning all, using UUIDs, or using integration names.

```json
{"channels": "*"}
```

```json
{"channels": ""}
```

```json
{"channels":
 "4ec5a071-2d08-4baa-898a-eb4eb3cd6941,746a083e-f542-4554-be1a-707ce16d3acc"}
```

```json
{"channels": "Email to Alice,SMS to Alice"}
```

--------------------------------

### GET /api/v3/channels/

Source: https://healthchecks.io/docs/api

Lists existing integrations.

```APIDOC
## GET /api/v3/channels/

### Description
Lists existing integrations.

### Method
GET

### Endpoint
https://healthchecks.io/api/v3/channels/

```

--------------------------------

### Concrete Slug URL Example

Source: https://healthchecks.io/docs/slug_urls

An example of a fully formed slug URL using a ping key and a descriptive slug.

```text
https://hc-ping.com/**fqOOd6-F4MMNuCEnzTU01w**/**db-backups**
```

--------------------------------

### GET|HEAD|POST /<uuid>/start

Source: https://healthchecks.io/docs/http_api

Sends a start signal to Healthchecks.io for a check identified by UUID. This indicates that the job has started.

```APIDOC
## [GET|HEAD|POST] /<uuid>/start

### Description
Sends a start signal to Healthchecks.io for a check identified by UUID. This indicates that the job has started.

### Method
GET, HEAD, POST

### Endpoint
https://hc-ping.com/<uuid>/start

### Response
#### Success Response (200 OK)
The request succeeded.

#### Success Response (200 OK, not found)
Could not find a check with the specified UUID.

#### Success Response (200 OK, rate limited)
Rate limit exceeded, request was ignored. Please do not ping a single check more than 5 times per minute.

#### Error Response (400 invalid url format)
The URL does not match the expected format.
```

--------------------------------

### Set timeout

Source: https://healthchecks.io/docs/api

Example of setting a 5-minute timeout in seconds.

```json
{"timeout": 300}
```

--------------------------------

### Run development server

Source: https://healthchecks.io/docs/self_hosted

Start the Django development server to access the application at http://localhost:8000.

```bash
$ ./manage.py runserver
```

--------------------------------

### Start SMTP listener with smtpd command

Source: https://healthchecks.io/docs/self_hosted

Starts the SMTP listener service on port 2525 to receive email pings. Run this command before sending test emails.

```bash
$ ./manage.py smtpd --port 2525

```

--------------------------------

### Configure SECURE_PROXY_SSL_HEADER in local_settings.py

Source: https://healthchecks.io/docs/self_hosted_configuration

Example of setting the SECURE_PROXY_SSL_HEADER as a tuple within the local_settings.py file.

```python
# in local_settings.py
SECURE_PROXY_SSL_HEADER = ("HTTP_X_FORWARDED_PROTO", "https")
```

--------------------------------

### Set timezone

Source: https://healthchecks.io/docs/api

Example of setting the server timezone.

```json
{"tz": "Europe/Riga"}
```

--------------------------------

### Generated ping URL examples

Source: https://healthchecks.io/docs/self_hosted_configuration

Examples of how Healthchecks generates ping URLs based on the PING_ENDPOINT configuration.

```text
https://ping.my-hc.example.org/3f1a7317-8e96-437c-a17d-b0d550b51e86
https://ping.my-hc.example.org/1fj9XWM6Ns8vLGTmnPGk9g/dummy-slug
```

--------------------------------

### Send a start signal endpoint format

Source: https://healthchecks.io/docs/http_api

The base URL structure for sending a start signal to a specific check using its ping key and slug.

```http
HEAD|GET|POST https://hc-ping.com/<ping-key>/<slug>/start
```

--------------------------------

### Send a start signal request

Source: https://healthchecks.io/docs/http_api

The base URL format for sending a start signal to a specific check identified by its UUID.

```http
HEAD|GET|POST https://hc-ping.com/<uuid>/start
```

--------------------------------

### Log Signal Example Request and Response

Source: https://healthchecks.io/docs/http_api

Example POST request to send a log signal with a body, followed by the 200 OK response. The response includes the Ping-Body-Limit header indicating how many bytes of the request body are stored.

```http
POST /fqOOd6-F4MMNuCEnzTU01w/database-backup/log HTTP/1.1
Host: hc-ping.com
Content-Type: text/plain
Content-Length: 11

Hello World
```

```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: *
Ping-Body-Limit: 100000

OK
```

--------------------------------

### Assign specific integrations by name

Source: https://healthchecks.io/docs/api

Example of assigning integrations by their unique names.

```json
{"channels": "Email to Alice,SMS to Alice"}
```

--------------------------------

### GET /api/v3/badges/

Source: https://healthchecks.io/docs/api

Lists the project's badges.

```APIDOC
## GET /api/v3/badges/

### Description
Lists the project's badges.

### Method
GET

### Endpoint
https://healthchecks.io/api/v3/badges/

```

--------------------------------

### GET /api/v3/status/

Source: https://healthchecks.io/docs/api

Checks database connectivity.

```APIDOC
## GET /api/v3/status/

### Description
Checks database connectivity.

### Method
GET

### Endpoint
https://healthchecks.io/api/v3/status/

```

--------------------------------

### Assign specific integrations by UUID

Source: https://healthchecks.io/docs/api

Example of assigning specific integrations using a comma-separated list of UUIDs.

```json
{"channels":
 "4ec5a071-2d08-4baa-898a-eb4eb3cd6941,746a083e-f542-4554-be1a-707ce16d3acc"}
```

--------------------------------

### GET /api/v3/checks/

Source: https://healthchecks.io/docs/api

Lists all existing checks in the account.

```APIDOC
## GET /api/v3/checks/

### Description
Lists all existing checks in the account.

### Method
GET

### Endpoint
https://healthchecks.io/api/v3/checks/

```

--------------------------------

### Set allowed HTTP methods

Source: https://healthchecks.io/docs/api

Example of restricting ping requests to POST only.

```json
{"methods": "POST"}
```

--------------------------------

### List existing checks with curl

Source: https://healthchecks.io/docs/api

Example request to list all checks using an API key in the header.

```bash
curl --header "X-Api-Key: your-api-key" https://healthchecks.io/api/v3/checks/
```

--------------------------------

### Set custom slug

Source: https://healthchecks.io/docs/api

Example of specifying a custom slug for a new check.

```json
{"slug": "my-custom-slug"}
```

--------------------------------

### Set schedule with cron expression

Source: https://healthchecks.io/docs/api

Example of a cron expression to run every half-hour.

```json
{"schedule": "0,30 * * * *"}
```

--------------------------------

### HEAD|GET|POST /<ping-key>/<slug>/start

Source: https://healthchecks.io/docs/http_api

Sends a 'job has started!' message to Healthchecks.io. This is optional but enables job execution time measurement and detection of jobs running longer than the configured grace time.

```APIDOC
## HEAD|GET|POST /<ping-key>/<slug>/start

### Description
Sends a "job has started!" message to Healthchecks.io. This is optional but enables job execution time measurement and detection of jobs running longer than the configured grace time.

### Method
HEAD, GET, POST

### Endpoint
https://hc-ping.com/<ping-key>/<slug>/start

### Parameters
#### Query Parameters
- **create** (integer) - Optional - Default "0". If set to "1", and if the slug in the URL does not match any existing check in the project, Healthchecks.io creates a new check automatically. Example: `create=1`
- **rid** (uuid) - Optional - Specifies a run ID of this ping. If run ID is specified, Healthchecks.io uses it to match the correct corresponding completion ping for this ping, and calculate an accurate duration. The value must be a client-picked UUID in the canonical textual representation. Example: `rid=123e4567-e89b-12d3-a456-426614174000`

### Request Example
```
GET /fqOOd6-F4MMNuCEnzTU01w/database-backup/start HTTP/1.0
Host: hc-ping.com
```

### Response
#### Success Response (200 OK)
The request succeeded.

#### Response Example
```
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: *
Ping-Body-Limit: 100000

OK
```

### Response Codes
- **200 OK** - The request succeeded.
- **201 Created** - A new check was automatically created, 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.
- **429 rate limit exceeded** - Rate limit exceeded. Please do not ping a single check more than 5 times per minute.
```

--------------------------------

### Configure SECURE_PROXY_SSL_HEADER via environment variable

Source: https://healthchecks.io/docs/self_hosted_configuration

Example of setting the SECURE_PROXY_SSL_HEADER environment variable to identify secure requests behind a proxy.

```bash
# environment variable
SECURE_PROXY_SSL_HEADER=HTTP_X_FORWARDED_PROTO,https
```

--------------------------------

### Filter checks by slug

Source: https://healthchecks.io/docs/api

Example URL for filtering checks by a specific slug.

```text
https://healthchecks.io/api/v3/checks/?slug=backups
```

--------------------------------

### Set check schedule

Source: https://healthchecks.io/docs/api

Examples of setting a check schedule using cron or OnCalendar expressions.

```json
{"schedule": "0,30 * * * *"}
```

```json
{"schedule": "*-*~1 12:00"}
```
Tokens:
Raw