Documentation
Complete guide to setting up website monitoring with PingZen. API documentation, code examples, and best practices.
An HTTP or HTTPS monitor sends a real request to a URL and decides whether the answer is healthy: the status code, optionally a keyword in the body or a value at a JSON path. It is the monitor to reach for when the thing you are watching speaks HTTP.
What It Is For
Websites and landing pages
Is the page still served, and does it still contain the text it should? A keyword check catches a blank page or a deploy that replaced your site with a default nginx welcome.
APIs and health endpoints
Point it at /health or /api/status, expect 200, and optionally assert a value at a JSON path — for example that status equals ok.
Endpoints behind authentication
Basic, Digest, Bearer token or an API key header. The credentials are stored encrypted and masked in every response.
Anything HTTP on any port
The URL may carry a port and a path: https://example.com:8443/health is a normal monitor. Nothing restricts the port.
A site that must not go down over its certificate
Renewal is automatic right up to the day it quietly breaks. An HTTPS monitor reads the expiry date off the same connection it uses to check the site, shows the countdown on the card, and sends a "Certificate Expiring" alert a week ahead. The site stays green while it does: a working certificate with a near date is something to renew, not an outage. You no longer need a second monitor just for the countdown.
What It Is Not For
The HTTP monitor sends an HTTP request and reads the answer. When that is the wrong shape of question, another monitor type fits better:
| You want to know | Use instead |
|---|---|
| The whole certificate picture — issuer, subject, SAN list, TLS version, and an amber status two weeks before expiry? An HTTPS monitor reads the expiry date and alerts on it, but records nothing else about the certificate | TLS/SSL certificate monitor |
| Is the certificate on a service that does not speak HTTP still valid (LDAPS, SMTPS, AMQPS, MQTTS)? | TLS/SSL certificate monitor |
| Does a multi-step flow still work — log in, add to cart, check out — in a real browser with JavaScript? | Transaction monitor |
| Does a sequence of API calls still work together, passing values from one response to the next? | API check monitor |
| How fast does the page feel — Core Web Vitals, Lighthouse scores? | PageSpeed monitor |
| Did my cron job or background worker run? Nothing is listening that you could poll | Heartbeat |
| Is a port open, when whatever listens on it does not speak HTTP? | TCP monitor |
| Is the host reachable at all, at the network level? | Ping (ICMP) monitor |
| Do my DNS records still resolve to the right values? Is my domain about to expire? | DNS monitor / WHOIS monitor |
| Is my mail server accepting connections, and is its IP on a spam blacklist? | SMTP / IMAP / POP3 monitors, DNSBL monitor |
| Is my WebSocket endpoint accepting connections? | WebSocket monitor (ws / wss) |
| Is my proxy working? | SOCKS5 / MTProxy monitors |
What It Checks
- The request goes out — your method, headers, authentication and timeout
- Redirects are followed if you leave that on, up to five hops, and the final response is the one judged
- The status code is compared against what you expect
- A keyword, if you set one — the body must contain it, must not contain it, or must match a regular expression
- A JSON path, if you set one — the value at that path must equal what you expect
What Counts As Up
If you leave the expected status at 200, the monitor also accepts the other success codes: 201, 202, 203, 204 and 206. Set any other value and the match becomes exact — expect 301 and only 301 will do.
| Response | Status | Why |
|---|---|---|
| Expected code, keyword and JSON checks pass | UP | Everything you asked for is there |
| HTTP 429 Too Many Requests | DEGRADED | The origin answered — it is throttling requests, not failing. No incident, and uptime is not reduced |
| Certificate chain is incomplete (missing intermediate) | DEGRADED | Browsers paper over it, other clients do not. Serve the full chain to fix it |
| Wrong status code, missing keyword, JSON mismatch | DOWN | The server is reachable but the answer is not the one you asked for |
| Expired, self-signed or untrusted certificate | DOWN | The handshake fails, so the request never happens. Turn off certificate verification if that is deliberate |
| Connection refused, DNS failure, timeout | DOWN | Nothing answered |
A 4xx is down by default, including 401, 403 and 404. The server is running, but the application returned an error, and that is what your visitors would see. If a 401 is the correct answer for the URL you monitor, set it as the expected status.
What an HTTPS Monitor Sees About the Certificate
An HTTPS monitor validates the certificate on every check — the chain must be trusted and the hostname must match — and it also reads the expiry date, off the connection it has already opened. No second handshake, no extra traffic, no change to how long a check takes. The consequence:
- a certificate that expires soon: the monitor shows how many days are left and, inside the critical window — 7 days, and never more than a sixth of the certificate’s own lifetime — sends a “Certificate Expiring” alert, at most once every 24 hours. The status does not change: the monitor stays green, no incident opens and no uptime is lost, because a certificate that still works is a warning, not an outage. Attach an alert with the Certificate Expiring trigger to receive it
- a certificate that has expired: the handshake fails, the monitor goes down, and the error says so
- a certificate signed by an authority nobody trusts: down, even though the site loads for you
Three values are stored per check: the date the certificate was issued, the date it expires and the days left. The issuer, subject, SAN list, TLS version and cipher are not — for those, and for an amber status two weeks ahead of expiry, add a TLS/SSL certificate monitor for the same host. Purely for the countdown a second monitor is no longer needed.
Redirects. The date is taken from the first hop of the redirect chain that is HTTPS on the monitor’s own host and port; a plain http:// monitor that redirects to https:// on the same host counts as a match. If the chain leaves for another host, the certificate there belongs to somebody else’s service, so nothing is recorded and the countdown stays empty. The Test Connection button in the monitor form flags a certificate that is already inside the warning window, 14 days by default.
For HTTPS monitors the certificate chain inspector on the monitor page shows the chain the server actually served, which is the quickest way to diagnose a missing intermediate.
Blocks, Bots and Parked Pages
Not every failure is your server’s fault, so the monitor labels the ones it can recognise:
- Bot protection — a WAF answered instead of your application. The WAF allowlist guide lists the addresses to let through
- ISP or DPI blocking — a probe cannot reach a site that is up elsewhere. See ISP blocking detection
- Parked or suspended pages — the domain resolves and returns 200, but the page is a registrar placeholder rather than your site. See parked page detection
- Rate limiting — 429, treated as degraded rather than down, as above
Configuration
URL
Full URL including scheme. A port and a path are allowed: https://example.com:8443/health. The scheme picks the protocol — https:// gives you an HTTPS monitor.
Method and headers
GET by default. HEAD is cheaper when you only care that the endpoint answers. Custom headers are sent as given — useful for a custom User-Agent when a WAF dislikes the default one.
Expected status
200 by default, which also accepts 201-204 and 206. Any other value must match exactly.
Keyword
Text that must be present, must be absent, or a regular expression the body must match. A keyword check is what separates "the server answered" from "the page is actually my page".
JSON path
For APIs: a path into the JSON response and the value you expect at it.
Authentication
None, Basic, Digest, Bearer token, or an API key in a header you name.
Follow redirects
On by default, up to five hops, and the final response is judged. Turn it off when the redirect itself is what you are testing — then set the expected status to 301 or 302.
Verify TLS/SSL certificate
On by default. Turn it off for a deliberately self-signed or internal certificate — the check then ignores trust and hostname problems entirely. The expiry countdown still works as long as the certificate names the host being checked — a certificate issued for somebody else says nothing about yours, so its dates are not recorded. Past the expiry date the monitor stays green, marks the certificate as expired and keeps sending the expiry alert for one more week before it goes quiet.
Key Features
- Status code, keyword and JSON-path checks in one request
- Keyword matching by contains, not-contains or regular expression
- Basic, Digest, Bearer and API-key authentication, stored encrypted
- Any port and any path, redirects followed or not as you choose
- Rate limiting recognised as degraded rather than a false outage
- Bot protection, ISP blocking and parked pages labelled instead of reported as a bare failure
- Certificate expiry read off the connection the check already makes, with a “Certificate Expiring” alert and no effect on status or uptime
- Certificate chain inspection on the monitor page
Common Questions
What protocols can I monitor?
PingZen supports 23 protocols: HTTP/HTTPS, WebSocket (WS/WSS), TCP, UDP, ICMP Ping, gRPC, DNS, WHOIS, TLS/SSL certificates, Email (SMTP/IMAP/POP3), FTP/FTPS, DNSBL, PageSpeed, SOCKS5, MTProxy, API Check, and Transaction. You can monitor websites, APIs, servers, databases, and any network service.
How fast can I get alerts?
Telegram alerts are delivered within 1-2 seconds of detection. Slack and Discord notifications arrive almost instantly. You can configure multiple alert channels for redundancy.
Can I organize monitors by project?
Yes! PingZen supports workspaces, which let you organize monitors by project, environment, or team. Each workspace can have its own alert configurations and team members.
Is there an API for automation?
Absolutely. PingZen provides a full REST API with OpenAPI documentation. You can create, update, and delete monitors programmatically.
How do status pages work?
Status pages are public, branded pages showing your services' uptime. You can display real-time status and allow customers to subscribe for updates.
What happens if I reach my monitor limit?
We'll notify you when approaching your limit. You can pause some monitors or contact us for increased capacity. We never stop monitoring without warning, ensuring your critical services stay protected.
Ready to stop missing downtime?
Join thousands of teams who trust PingZen. Setup takes 30 seconds.