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.

OptionDefaultNotes
methodGETGET, POST, PUT, PATCH, DELETE, HEAD
headers—Extra request headers, merged over the defaults
body—Raw request body string
expectedStatusCodes200–208, 226Any 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
followRedirectstrueWhen false, a redirect response is evaluated against your expected codes instead of being followed
verifyTlstrueWhen 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.

OptionDefaultNotes
recordTypeAA, AAAA, CNAME, MX, TXT, NS
expectedValue—At least one returned record must contain this substring
resolversystem resolverDNS 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:

OptionDefaultEffect
warningDays14Days remaining ≤ this → degraded (amber, no alert)
criticalDays3Days remaining ≤ this → down (incident + alerts)
port443TLS 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.

  1. Create a push monitor. PingBoard generates a secret token for it.
  2. Have your job POST to 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.

Edit on GitHub·Found an issue? Open a PR.