Publish Upcoming Maintenance Before It Starts
Sources and verification
- Source dates
- Oldest source check: 12 September 2026.
- Technical verification
- Separate technical verification has not been recorded.
Publication approval and technical verification are recorded separately. Automated link checks establish reachability, not accuracy. A checked example verifies only its stated test cases, not the whole article or your production setup.
In short
Keep scheduled maintenance in an explicit record with start, end, affected services, status, and a stable identifier. Publish the record before the window starts, and derive both customer messaging and monitoring suppression from it. Do not assume an endpoint showing active maintenance also lists future events. Test planned, postponed, cancelled, active, and overdue states separately.
Key takeaways
- Upcoming maintenance and active suppression are different views of one event.
- A stable maintenance ID keeps customer notices and monitoring aligned.
- Cancellation and delayed completion need explicit state changes.
Check what the existing API actually returns
Create a future maintenance event in a test environment and inspect the supported endpoint used by the application. Record the installed version and response before, during, and after the window. An empty active-maintenance list does not prove that no future maintenance is scheduled.
The Uptime Kuma maintenance documentation (opens in a new tab) explains maintenance concepts, but verify the exact interface and authentication available in your release. Avoid scraping an internal UI response or relying on an undocumented socket event without accepting and testing that maintenance burden.
If the monitoring product cannot expose the upcoming events you need, use a small dedicated maintenance record as the source of truth and publish a sanitized projection to customers.
Define the event contract
{
"id": "maint-2026-09-20-search",
"status": "scheduled",
"starts_at": "2026-09-20T00:00:00Z",
"ends_at": "2026-09-20T01:00:00Z",
"display_timezone": "Europe/Berlin",
"services": ["search"],
"summary": "Search indexing maintenance",
"updated_at": "2026-09-12T10:00:00Z"
}
This example is your own public schema, not a Uptime Kuma API payload. Keep internal runbooks, employee contact details, and suppression credentials outside the public response. Make public service identifiers stable and map them to internal monitor IDs in a restricted configuration.
Store unambiguous timestamps and render the local time with its zone. A date and “01:00” without an offset can become ambiguous around a daylight-saving transition. For recurring maintenance, materialize and inspect future occurrences rather than assuming one recurrence rule will be interpreted identically by every consumer.
Derive the two views
The customer view selects future scheduled events and currently active ones. It should say which services are affected, the expected user impact, and when the information was updated. Define what happens when the feed cannot be fetched: keep a visible stale marker instead of silently showing “no maintenance.”
The monitoring view enables suppression only for the affected checks and only within the authorized window. Use the same event ID for audit history. A notice displayed next week must not suppress alerts today, and an unrelated service must remain monitored during the window.
Handle changes as first-class operations
| Event change | Required behavior |
|---|---|
| Start postponed | Update notice and suppression together |
| Cancelled | Remove future suppression and show cancellation where appropriate |
| Starts early | Explicit authorization and updated customer state |
| Runs past expected end | Update public state; review suppression expiry |
| Completed | End suppression and confirm fresh service checks |
Do not automatically announce successful completion merely because the planned end time passed. Confirm the work and the post-maintenance service checks. An overrun should remain visible to both operators and customers.
Prove the integration with one test event
Use a harmless test service and a short future window. Confirm the notice appears in advance, suppression starts on time, unrelated checks still alert, cancellation works, and normal monitoring resumes. Test stale caches as well as fresh API responses. Keep one responsible owner for the event so mismatched clocks or an interrupted integration do not leave customers and responders following different schedules.
Did this help?
Your answer helps us improve this guide. We save only the page and your choice for 30 days.
No name, email, or incident details are requested.
Sources
Vendor facts change. Each source below shows the date this page last checked it.
- Uptime Kuma maintenance — Uptime Kuma. Checked 12 September 2026.
Related
One practical idea, occasionally
The On-Call Brief: short field notes, templates, and operational lessons.
Follow the field guide
Email subscriptions are not open yet. Read new guides in your feed reader — no email address needed.
Subscribe with RSS