Maintenance windows

A maintenance window is a span of time you declare in advance over part or all of your organisation. An incident that opens inside one is silenced: no alert is created for it, and no all-clear is created when it recovers.

Schedule one before a deploy, a migration, a datacentre move — anything you already know will take a target down — and nobody is paged for the outage you planned.

What a window is

Field	What it is
title	a free-text label; optional, and empty by default
scope	what the window covers
target_id	the monitor or Service it covers; absent for an organisation-wide window
starts_at	when the window opens
ends_at	when the window closes

There is no recurrence. A window is one span, and a weekly maintenance slot is a new window each week.

The three scopes

A window’s scope is one of monitor, service, org.

Scope	Covers	target_id
org	every monitor in the organisation	must be absent
monitor	that one monitor, and nothing else	the monitor’s id
service	every monitor whose Service is that Service	the Service’s id

A monitor with no Service is never covered by a service-scoped window. Coverage is decided by comparing the window’s target against the monitor’s Service, and a monitor that is in no Service has nothing to compare — so it is not covered, and nothing anywhere tells you it was skipped. If you schedule by Service, check first that every monitor you meant to cover is actually in it.

A window only ever covers monitors in the organisation that owns it. There is no scope that reaches across organisations, and a window in another organisation cannot silence yours.

What a window is doing right now

Every window reports a state derived from the clock. It is not stored, so there is nothing to keep in sync and no window that is active in the record and over in fact.

State	When
upcoming	now is before starts_at
active	starts_at ≤ now < ends_at
past	now is at or after ends_at

The interval is half-open: a window is active from starts_at inclusive, and stops being active the instant ends_at arrives.

The stamp is taken when the incident opens

This is the rule that surprises people, and it is why a maintenance window behaves unlike every other kind of silence in WireWatch.

Whether an incident is under maintenance is decided once, at the moment the incident is created, and the answer is written onto the incident. It is never looked up again. Three things follow:

• A window declared mid-incident changes nothing about that incident. The stamp was taken when it opened and there was no window then, so its alerts keep arriving. To silence an incident that is already running, snooze it.
• An incident that opened inside a window is silent for its whole life, its resolve all-clear included. It does not start alerting when the window ends, and it never sends the recovery notice for an outage nobody was told about.
• Deleting the window does not un-silence the incidents it caught. The stamp lives on the incident, not in a lookup against a window that has to still exist.

You cannot set that stamp yourself. Nothing in the API or the dashboard writes it; WireWatch writes it at open time and nothing else ever touches it.

Snooze defers, maintenance discards

A snooze holds notifications back until an instant and then lets the incident alert again — what was held arrives late rather than not at all. A maintenance window holds nothing back: the notifications are never created, and they do not turn up afterwards. The full list of reasons an alert did not arrive, these two among them, is on Suppression.

Who can schedule one

Permission	Held by
maintenance:read	Owner · Admin · Editor · Viewer · Billing
maintenance:manage	Owner · Admin

Every role can see the windows. Only an Owner or an Admin can create, edit or delete one — which means an Editor who can create a monitor cannot schedule that monitor’s maintenance. That is the same line the rest of alerting is drawn on rather than a quirk of this screen: channel:manage stops at Admin too, while monitor:write reaches an Editor. Configuring what is watched and deciding who gets woken are separate powers here.

What is refused

• ends_at at or before starts_at returns 400. A window has to span forward in time. The API refuses it, and the maintenance_windows_time_order constraint refuses it again in storage, so it cannot be written by any route that forgets to check.
• A target_id on an organisation-wide window, or none on a monitor- or service-scoped one returns 400. Exactly the org scope carries no target. The maintenance_windows_scope_target constraint is the storage backstop for the same rule.
• A monitor or Service that does not exist in your organisation returns 404. A target that exists in another organisation answers exactly as one that does not exist at all — WireWatch will not tell you which of the two it was.