Monitor types
What each of the six check types verifies and every per-type config option.
PingBoard has six monitor types. All share the scheduling options in Monitors; this page covers what each type checks and its type-specific configuration.
HTTP(S)
Checks a URL with a real HTTP request. PingBoard sends a descriptive User-Agent (PingBoard/1.0 (uptime monitor; +https://github.com/steiner-co/pingboard)) because UA-less requests get 403'd by many WAFs and read as false downs.
| Option | Default | Notes |
|---|---|---|
method | GET | GET, POST, PUT, PATCH, DELETE, HEAD |
headers | — | Extra request headers, merged over the defaults |
body | — | Raw request body string |
expectedStatusCodes | 200–208, 226 | Any status outside the list is a failure |
expectedKeyword | — | Body must contain this substring |
expectedJsonPath | — | { "path": "a.b.c", "equals": <value> } — the dot-separated path in the parsed JSON body must deep-equal equals |
followRedirects | true | When false, a redirect response is evaluated against your expected codes instead of being followed |
verifyTls | true | When false, certificate errors are ignored (expired/self-signed certs still connect) |
Keyword and JSON-path assertions turn a plain ping into a semantic check: expectedKeyword: "\"status\":\"ok\"" on a health endpoint, or expectedJsonPath with path: "database" and equals: "up" to fail when a dependency goes sideways even though the page returns 200. A body that isn't valid JSON when expectedJsonPath is set counts as down.
TCP
Opens a TCP connection and closes it — up if the handshake completes. Use it for databases, mail servers, SSH, anything that speaks TCP.
Target is host:port (e.g. db.internal:5432), or a bare host with the port set in the type config (port).
Ping
ICMP echo via the system ping binary (ping -c 1 -W <timeout> <target> — the Docker image ships iputils for this). The reported response time is the real round-trip time parsed from ping's output. Target is a hostname or IP.
Note this checks ICMP reachability, which many networks rate-limit or filter — a failed ping doesn't always mean the service is down.
DNS
Resolves a record and optionally matches its content — useful for catching DNS hijacks, bad failover, or a missing SPF record.
| Option | Default | Notes |
|---|---|---|
recordType | A | A, AAAA, CNAME, MX, TXT, NS |
expectedValue | — | At least one returned record must contain this substring |
resolver | system resolver | DNS server IP to query instead, e.g. 1.1.1.1 |
No records of the requested type at all counts as down. TXT records are joined before matching, so multi-string TXT values match as one string.
SSL certificate expiry
Connects over TLS, reads the peer certificate's expiry date, and compares days remaining against two thresholds:
| Option | Default | Effect |
|---|---|---|
warningDays | 14 | Days remaining ≤ this → degraded (amber, no alert) |
criticalDays | 3 | Days remaining ≤ this → down (incident + alerts) |
port | 443 | TLS port |
Target can be a bare hostname, host:port, or a full URL (the host and port are extracted). The check intentionally doesn't reject invalid certificates — it needs to read the dates even from an already-expired cert, and expiry comparison is the actual check. Every result records the days remaining, so you can see the runway on the monitor page.
Domain expiry
Domain expiry is no longer a monitor type — a domain isn't a target you poll, it's an asset you track. Since 1.0, domains live on their own Domains page in the dashboard: expiry and renewal runway, registrar, nameservers, and the SSL certificate across your whole portfolio, auto-detected via RDAP (with a WHOIS fallback for ccTLDs without it) or entered by hand, with alerts before anything lapses. The v1.0 announcement covers why the split happened. For certificate expiry on a specific endpoint, use the SSL type above.
Push (heartbeat)
Inverts the direction: instead of PingBoard polling a target, your job pings PingBoard. Ideal for cron jobs, backups, and batch pipelines that run inside networks you can't reach.
- Create a push monitor. PingBoard generates a secret token for it.
- Have your job
POSTto the push URL when it finishes:
curl -X POST https://status.example.com/api/push/<token>An empty body means "up". To report richer results, send JSON:
{
"status": "up",
"message": "nightly backup completed",
"responseTimeMs": 4200
}status may be up, down, or degraded; message is capped at 500 characters; responseTimeMs is any non-negative number. Reporting down yourself opens an incident immediately.
Grace period. PingBoard expects a heartbeat every intervalSeconds. If none arrives within intervalSeconds + graceSeconds (grace defaults to 30 seconds), an overdue scan that runs every 10 seconds marks the monitor down and opens an incident with a "No heartbeat received" message. For a nightly backup, set the interval to 1 hour (3600) and schedule the job well inside it; for a 5-minute cron, use the 5-minute interval (300). Paused push monitors acknowledge heartbeats but ignore them.
