Documentation
Complete guide to setting up website monitoring with PingZen. API documentation, code examples, and best practices.
Maintenance Windows
Maintenance Windows let you schedule downtime. During the window, alerting is paused for the selected monitors so your subscribers don’t get flooded with false alarms. Pinger handles the timing and the public-page visibility for you — including a deferred “all-clear” notification if anything actually went wrong.
Features
Scheduling
Schedule maintenance in advance with start and end times. Pinger automatically transitions a window through its lifecycle — you don’t have to flip it to “Active” or “Completed” yourself unless you want to.
Alert Suppression
Alerts for selected monitors are not sent during maintenance. This covers both DOWN alerts (when a monitor goes critical inside the window) and RECOVERED alerts (when it comes back).
Deferred Recovery Alerts
If a monitor went DOWN inside the window and is healthy again by the time the window ends, Pinger fires a synthesized “all-clear” RECOVERED alert the moment the window completes. Subscribers always learn the outage is over — even though no natural state transition happened during the window.
Status Page Display
Visitors see scheduled and active maintenance on the public status page. After a window completes, what stays visible depends on whether anything actually went wrong (see Public-page visibility below).
Maintenance History
Complete history of all past maintenance for reporting and SLA review.
Maintenance Statuses
Scheduled
Maintenance is scheduled for the future.
Active
Maintenance is happening right now.
Completed
Maintenance completed successfully.
Cancelled
Maintenance was cancelled.
Public-page visibility
Pinger does not treat every completed maintenance window the same way on the public status page. The rule of thumb: clean windows disappear immediately, dirty ones stick around for a day with an incident-count badge.
A window is considered dirty if a monitored failure occurred on one of its affected monitors while it was active (Pinger detects this automatically — there is nothing to toggle by hand). Otherwise it is clean.
Scheduled + Active — always visible on the public page (your advance promise to visitors).
Completed + clean — drops off the public page as soon as the window ends. The status page stays uncluttered after routine zero-impact maintenance.
Completed + dirty — kept on the public page for 24 hours after the end time with a red badge showing how many incidents occurred during the window. Subscribers can see what happened without digging through history.
Cancelled + dirty — same 24-hour treatment. If you pulled the plug mid-incident, the audit trail stays visible to visitors.
Cancelled + clean — never appears on the public page. Operator changed plans, nothing to communicate.
The full history of every window — clean or dirty, completed or cancelled — is always available in the authenticated dashboard for reporting and SLA review.
Lifecycle
A maintenance window moves through up to four states automatically. You can also cancel it at any time before it completes.
SCHEDULED — visible on the status page from the moment you create it. Alerts still fire as normal during this phase.
IN_PROGRESS — the scheduler flips the window here automatically at start time. Alerts for affected monitors are suppressed. Any monitored failure during this window auto-tags the row as "dirty".
COMPLETED — auto-transition at end time. If anything went wrong, a deferred "all-clear" RECOVERED alert fires now. Clean windows leave the public page immediately; dirty ones stick around 24 hours.
CANCELLED — operator-initiated abort. If the cancel happens mid-incident, the row stays public 24h with the incident badge; otherwise it disappears immediately.
Example: planning a database migration
Suppose you’re upgrading PostgreSQL on Friday at 02:00 UTC. Expected duration: 2 hours. Affected monitors: api.example.com (HTTPS) and db-health (TCP). Status page: example.
Monday — schedule it. Title: "PostgreSQL 16 upgrade". Description: "Brief read-only window while we cut over the primary. API may return 503 for ~5 min." Affected monitors: those two. Save. Visitors to example immediately see "Scheduled maintenance Friday 02:00 UTC".
Friday 02:00 — window auto-opens. Banner on the public page switches to "Maintenance in progress". Alerts for the two monitors are silenced from this minute. You don't have to click anything.
02:14 — the cutover takes longer than expected, API returns 503. Pinger silently records the failure on api.example.com and tags the window as "dirty" — no alert is sent (you asked for that), but the audit trail is preserved.
02:31 — service back to healthy. No alert fires yet (still under maintenance), but Pinger remembers the recovery.
Friday 04:00 — window auto-closes. Public page shows "Recent maintenance with incidents · 1 incident during this window". Subscribers receive a single "all-clear" RECOVERED alert. Window stays visible 24 hours; then auto-hides while remaining in the dashboard history forever.
How to Create
- Go to “Maintenance” in the sidebar
- Click “Schedule Maintenance”
- Enter a title and description
- Select start and end date/time
- Select affected monitors
- Save — maintenance will appear in the calendar
What subscribers experience
During the window — no DOWN alerts and no RECOVERED alerts for any affected monitor. The status page banner replaces the per-monitor green dots with "Maintenance in progress".
After a clean window — silence. No alerts. The status page returns to normal. Nothing changed for your subscribers.
After a dirty window — a single deferred RECOVERED alert per monitor that's now healthy, plus the public-page card stays visible 24 hours with the incident count. Subscribers learn what happened in one notification, not a flood.
Tips
Schedule maintenance in advance so users are notified via the status page.
Provide detailed descriptions for transparency.
After completion, verify all monitors return to UP status — if any are still DOWN, alerts resume naturally on the next check.
Pad the end time a bit — better to over-estimate. A window that runs over is awkward; one that ends cleanly with five spare minutes is professional.
FAQ
Why did my last maintenance window disappear from the status page right after it ended?
Because nothing went wrong inside it. Pinger hides clean completed windows immediately to keep the status page focused on what matters. The full record is still in the dashboard.
My maintenance ended an hour ago but a red card with “1 incident during this window” is still on the public page — is that a bug?
No — that’s the 24-hour grace for windows where Pinger detected at least one monitored failure. It’s there so visitors and SLA reviewers can see what happened. It auto-hides exactly 24 hours after the scheduled end time.
Can I clear the “dirty” flag manually?
No. The flag is system-driven and monotonic — once set, only time auto-hides it. This is by design: an SLA dispute is much easier to handle when the audit trail can’t be retroactively edited.
Will subscribers get spammed with alerts during a long maintenance window?
No. Both DOWN and RECOVERED alerts are suppressed for the affected monitors for the whole duration of the window. If something went wrong, subscribers get exactly one “all-clear” notification when the window completes.
What if my maintenance runs over the scheduled end time?
The window transitions to COMPLETED automatically at the scheduled end. Any incidents that fire after that point are treated as real outages and trigger normal alerts — they’re not suppressed. Pad the end time generously to avoid this.
Can I cancel a maintenance window after it’s already started?
Yes — go to “Maintenance” in the sidebar and click Cancel. If incidents already occurred inside the window, the cancelled-with-incident row stays on the public page for 24 hours with the audit context. If nothing went wrong, it disappears immediately.
Does workspace-wide maintenance (no specific monitors selected) affect every monitor?
Yes — leaving the “Affected monitors” field empty applies the suppression and tagging behaviour to every monitor in the workspace. The incident count on the public page is scoped to monitors that are actually shown on that status page, so the badge stays meaningful.
What’s the difference between Scheduled and In progress?
Scheduled means the start time hasn’t been reached yet. Alerts still fire as normal. In progress means the start time has passed and the window is now suppressing alerts. Pinger flips the state automatically — you don’t need to click anything.
Troubleshooting
"My window is still SCHEDULED 5 minutes after the start time." The auto-transition runs once a minute. Wait up to 60 seconds. If it still hasn't flipped, contact support — the maintenance scheduler may be offline.
"Subscribers got a DOWN alert during my window." Check that the failing monitor was actually in the window's "Affected monitors" list. Suppression is per-monitor, not workspace-wide unless you left the list empty.
"The badge says nothing even though I'm sure something went wrong." The count covers only incidents that started inside the window's start/end times. If an incident started before the window opened, it's not counted toward the window — it's its own pre-existing outage. The badge appears only when the count is greater than zero.
"My subscribers never got the 'all clear' alert." The deferred RECOVERED alert fires only if the monitor is healthy at window-completion time. If it was still DOWN when the window closed, the next normal check will trigger the recovery once it actually comes back.
Maintenance API
Manage maintenance windows via REST API. The public status-page endpoint also exposes the same data (read-only) and applies the visibility filter described above.
List maintenance with filters (admin)
Create scheduled maintenance
Update maintenance
Cancel maintenance
Delete maintenance window
Public list — applies the visibility filter described above
Common Questions
What protocols can I monitor?
PingZen supports 23 protocols: HTTP/HTTPS, WebSocket (WS/WSS), TCP, UDP, ICMP Ping, gRPC, DNS, WHOIS, 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.