health-check/docs/ping-payload.md

Ping Payload Standard

This document defines the standard payload for all health check pings sent to Healthchecks.io across all agents (scripts, bots, services).

Why not use an existing library?

The healthchecks-io package on PyPI focuses on the management API and does not send a custom body payload. This library fills that gap with an opinionated, consistent payload that identifies the agent, device, IPs, and uptime on every ping.

---

Using as a Python module

Install directly from the repository:

pip install git+https://github.com/SantosFC/health-check.git

Basic usage

from health_check import ping, ping_fail

url = "https://hc-ping.com/<your-uuid>"

try:
    status = ping(url, agent="my-telegram-bot", device="my-server")
    if 200 <= status < 300:
        print("Ping OK")
    else:
        ping_fail(url, agent="my-telegram-bot", device="my-server")
except Exception as exc:
    ping_fail(url, agent="my-telegram-bot", device="my-server")
    raise

Loading config from file

from health_check import load_config, ping

config = load_config()  # reads ~/.config/health-check
ping(config["HEALTHCHECK_URL"], agent="my-bot", device=config["DEVICE_NAME"])

Custom config path

from pathlib import Path
from health_check import load_config

config = load_config(config_file=Path("/etc/my-bot/config"))

Timeout

ping(url, agent="my-bot", device="server", timeout=5)

---

HTTP Request

• Method: POST
• URL: https://hc-ping.com/<uuid>

Headers

Header	Value
User-Agent	health-check/<version>
Content-Type	application/json

Body

{
  "user": "<agent-name>",
  "device": "<device-name>",
  "ips": ["<ip1>", "<ip2>"],
  "uptime": "<Xd Yh Zm>"
}

Field	Type	Description
user	string	Name of the agent sending the ping (script, bot, service)
device	string	Name of the device or host where the agent runs
ips	array of strings	List of IP addresses of the device
uptime	string	Device uptime formatted as Xd Yh Zm

Example

{
  "user": "my-telegram-bot",
  "device": "my-server",
  "ips": ["192.168.1.10", "10.0.0.5"],
  "uptime": "3d 14h 22m"
}

Failure Ping

On error, agents must send a POST to <uuid>/fail with the same body. The ping_fail function handles this automatically.