Documentation
Complete guide to setting up website monitoring with PingZen. API documentation, code examples, and best practices.
A WHOIS monitor asks the domain registry how long your registration still has to run. It reads the expiry date and the registrar name, counts the days left, and turns amber long before the date arrives. It touches nothing on your server — the answer comes from the registry, not from your host.
What It Is For
The renewal nobody remembers
A domain is renewed once a year, or once every few years. Nothing in your daily work reminds you of it. The renewal notice goes to a mailbox on that same domain, or to a person who left the company, and the card on file at the registrar expired months ago.
Domains you do not pay for yourself
Client domains, domains a marketing team bought, domains inherited with a project. You run the servers but somebody else holds the registrar account. A monitor gives you the warning that the billing email never sends you.
Catching a hold before users do
Registries suspend names for unpaid renewals, failed contact verification or a dispute. The monitor reads the registration status, so a domain put on hold or removed from delegation is reported as down even if the expiry date is still months away.
Keeping the registration facts in one place
Every check stores the expiry date and the registrar name on the monitor, so "when does this expire and who did we buy it from" has an answer without logging into anything.
What It Is Not For
This monitor looks at the registration record, and at nothing else. The domain can be registered for another five years while the site is dead.
| You want to know | Use instead |
|---|---|
| Does the TLS certificate expire soon? That is a different date with a different owner and a different consequence | TLS/SSL certificate monitor |
| Do the DNS records still resolve, and do they answer with the right address? | DNS monitor |
| Is the site up right now? | HTTP / HTTPS monitor |
| Did somebody change the nameservers, an A record or an MX record at the registrar? PingZen never reads your registrar account — but it can watch the result those settings produce | DNS monitor with expected values |
| Is mail for the domain still being accepted? | SMTP monitor on the mail host |
| Is the domain or the mail server on a spam blacklist? | DNSBL monitor |
Domain Expiry Is Not Certificate Expiry
The two monitors have the same shape — both count days down to a date — and they are often confused. The dates belong to different systems, and so do the consequences.
| Certificate expiry | Domain expiry | |
|---|---|---|
| Who holds the date | The certificate authority | The domain registry and your registrar |
| How often it comes round | Every few days to a few months, usually renewed automatically | Once a year or less, usually renewed by a payment |
| What breaks when it passes | HTTPS. The site is still there, browsers refuse to open it. Plain HTTP, mail and DNS keep working | The name itself. The site, every subdomain, all mail to the domain, any login that uses that mail — all gone at once |
| How hard it is to undo | Issue a new certificate, minutes | Redemption fees, days of waiting, and after that window somebody else can register the name |
That last row is the reason the defaults here are wider than on the certificate monitor. A late certificate costs you an afternoon; a late domain can cost you the name.
For a domain that also serves a website, run both monitors. They watch two dates that have nothing to do with each other.
What It Checks
Each check performs one lookup and records:
- Days until expiry — from the registration expiry date
- Expiry date — shown on the monitor page in your own time format
- Registrar — the name the registry reports for the sponsoring registrar
- Registration status — used to detect a hold or a name that is no longer delegated
Data comes from RDAP first, the modern structured replacement for WHOIS. When a TLD has no RDAP service — .ru, .de and .cn among others — the check falls back to a classic WHOIS query automatically. You do not choose between them.
For .com and .net, a WHOIS answer often carries two expiry dates: one from the registry, one from the registrar. The registry date can be pushed forward automatically while the invoice is still unpaid, so PingZen always takes the earlier of the two. A monitor that showed the later date would go green on a domain that is not actually paid for.
Expiry Thresholds
Two day counts decide when the monitor reacts.
Domain Expiry Warning (days) — default 30
Once this many days or fewer remain, the monitor turns amber and sends a "Degraded" alert. Uptime is untouched — the domain still works, it just needs a payment.
Critical (days) — default 7
Below this the monitor page paints the days-left badge red instead of yellow, and the check message is marked CRITICAL. The status stays amber: an unexpired domain is never counted as an outage.
30 days is a deliberate choice. Registrars bill on a yearly cycle, an expired card or an unanswered invoice takes real days to sort out, and nothing about a domain renewal is automatic the way a certificate renewal is. If your registrar auto-renews reliably, lower it; if payment goes through a finance department, raise it.
These thresholds are not scaled down for short registrations. The certificate monitor caps its thresholds by the certificate lifetime, because certificates now live for days and a fixed 7-day critical band would never switch off. Domain registrations are sold in whole years, so there is nothing to cap: the numbers you set are the numbers used.
What Each Status Means
| Situation | Status | What you get |
|---|---|---|
| More days left than the warning threshold | UP | Days remaining, expiry date and registrar on the monitor page |
| Inside the warning window | DEGRADED | Amber badge and a "Degraded" alert when it enters. No incident, no uptime loss |
| Inside the critical window | DEGRADED | Same status, red days-left badge, check message marked CRITICAL |
| The expiry date has passed | DOWN | Incident opens, down alert fires, message names the date it expired |
Registrar hold, redemption, pending delete, or a .ru domain no longer delegated | DOWN | Incident opens, message names the status the registry returned |
| The answer arrived but carried no expiry date | DEGRADED | "Could not determine domain expiration date". The registrar is still shown. No incident |
| The lookup itself failed — registry refused the query, no RDAP and no WHOIS service for the TLD | DOWN | Incident opens, message carries the error from the registry |
| The lookup took longer than the timeout | TIMEOUT | Counts as downtime, same as any other timeout |
A failed lookup counts against the monitor even though your domain may be perfectly fine — the check could not prove otherwise. Registries do rate-limit and go down for maintenance, which is one more reason to keep the interval long.
Configuration
Domain
The registered domain itself: example.com. A scheme, a path and a port are stripped, so pasting https://example.com/pricing works. Use the domain you actually registered, not a subdomain — www.example.com and api.example.com have no registration record of their own. Domains under a multi-part suffix such as .co.uk are handled correctly.
Domain Expiry Warning (days)
When the monitor turns amber. Default 30, range 1 to 365, and never below the critical value.
Critical (days)
When the days-left badge turns red. Default 7, range 1 to 30. The monitor form shows the warning field only; the critical value keeps its default unless you set it through the API or the MCP tools.
Check interval
Choosing WHOIS sets the interval to 24 hours and the timeout to 30 seconds. A registration date changes once a year — one lookup a day is already generous, and registries answer frequent automated queries with rate limits. One day is also the longest interval PingZen allows.
Alerts
Degraded — the one that matters
Attach an alert with the Degraded trigger. It fires the day the monitor crosses your warning threshold. This is the message that saves the domain; everything after it is already an emergency.
Down
Fires when the domain has expired, when the registry reports a hold, and when the lookup fails. An incident opens with it.
"Certificate Expiring" does not apply here
That trigger reads certificate dates and fires only for monitors that read a certificate. A domain countdown never uses it, so do not wait for it on a WHOIS monitor.
By default you get one message, not a daily reminder. The alert fires on the transition into the amber state; while the monitor stays amber, nothing is repeated unless that alert has reminders enabled, in which case the Degraded message is re-sent once every 24 hours until the state clears. Crossing from the warning band into the critical band is not a status change either, so it sends nothing on its own. Set the warning threshold to the lead time you actually need, and treat that single message as the deadline. See alerts for channels and routing.
Key Features
- RDAP first, automatic WHOIS fallback for TLDs that have no RDAP service
- Takes the earlier of the registry and registrar expiry dates, so an unpaid renewal cannot look healthy
- Detects registrar hold, redemption and pending-delete states, and non-delegated
.rudomains - Expiry date and registrar name stored with every check and shown on the monitor
- Warning and critical day thresholds with no lifetime scaling — the numbers you set are the numbers used
- An expiring domain is amber, not an outage: no incident, no uptime lost
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.