Custom domains

By default a status page is served from WireWatch’s own origin, at <public status base>/<slug>. A custom domain lets you serve the same page from a name of your own — status.acme.com — so that the page a customer lands on during an outage is still on your domain.

Adding one does not move the page. The slug URL keeps working, the page is the same page, and the custom domain becomes a second way in. What the page looks like once it is there is a separate matter — see appearance and branding.

Your plan has to include custom domains

Adding a custom domain is gated on the custom_domain entitlement, and the check runs before anything is claimed or registered. On a plan that does not include it the add is refused outright: no name is held, nothing is registered with the edge, and the claim-then-wait below never starts.

The refusal is a 403 whose body reads feature_gated and names the feature. That is a different answer from the plain forbidden 403 further down this page, and it needs a different fix: a feature_gated refusal is about your plan and no role change will clear it, exactly as it works for branding. Which plans include custom_domain is a billing question and changes with pricing, so it is on your organisation’s billing screen rather than restated here.

Adding one is a claim, then a wait

Adding a domain is three things happening in order, and only the first is over when the request returns.

1. You claim the name. WireWatch records the domain against your page and registers it with the edge that will terminate TLS for it.
2. You point DNS at us. The response to the add tells you exactly which records to create — a CNAME for the domain itself, and, when the edge asks for it, a TXT record proving you own the name. Nothing works until those exist at your DNS provider.
3. The edge checks, and you refresh. Verification is not something WireWatch decides; it is the edge confirming your DNS and issuing a certificate. Refreshing a domain re-reads that answer and stores it.

So a domain you added a minute ago and have not configured DNS for is behaving exactly as designed. It is claimed, it is not verified, and it does not serve.

The name is claimed across all of WireWatch

A domain belongs to exactly one status page across every organisation on WireWatch, not just across yours. It is the same rule the slug follows, for the same reason: the name resolves on the public internet, so it cannot be scoped to an account.

Adding a domain another page has already claimed is refused with 409, and the answer does not tell you who holds it. You are not told whether the holder is one of your own pages or a stranger’s, and you cannot use the endpoint to find out whether some other company has claimed a name. The refusal happens on the constraint, before anything is registered anywhere.

Re-adding a domain after a failure

Adding a domain is not one step internally, and an attempt can fail part-way — the claim lands and the registration that follows it does not. That leaves a claim of yours holding the name and nothing serving it.

Adding the same domain to the same page again works. WireWatch adopts your own half-finished claim and carries on from it rather than answering 409 against your own leftover, so the fix for a failed add is to do it again. This applies to your own claim on your own page only; a name genuinely held elsewhere still answers 409.

The three states

A domain is always in exactly one of 3 states: pending, active, error.

• pending — claimed, and not verified yet. This is the state every domain starts in, and it is where a domain sits while it waits for your DNS records and for a certificate.
• active — verified. The domain has been confirmed and a certificate is in place.
• error — the edge tried and could not finish. Almost always this is DNS: the CNAME points somewhere else, the TXT record was never created, or a proxy in front of the name is answering the validation request instead of passing it through.

What to do about error

An error is not terminal and it does not need a support ticket. Fix the record the edge could not see, then refresh the domain — the refresh re-asks and rewrites the state, so a domain can go from error back to pending and on to active without being removed and re-added. If the name itself was a mistake, remove it and add the right one.

Only active serves

A custom domain serves only while it is active and the page is published.

Both halves matter, and they fail the same way. A request to a domain that is pending or error, or to an active domain whose page you have not published, does not get an error explaining which: it gets the same 404 an unknown domain gets. That is deliberate — the public entry point cannot be used to find out whether a page exists, so it does not distinguish “not yours”, “not verified” and “not published”.

Which means the order that works is the same one the slug path uses: add the domain, set the DNS, wait for active, publish. A page that is already live simply gains a second address the moment verification lands.

Who may manage a domain

Operation	Route	Permission
Add a domain	POST /orgs/:orgId/status-pages/:pageId/domains	status_page:manage
List a page’s domains	GET /orgs/:orgId/status-pages/:pageId/domains	status_page:manage
Refresh verification	POST /orgs/:orgId/status-pages/:pageId/domains/:domainId/refresh	status_page:manage
Remove a domain	DELETE /orgs/:orgId/status-pages/:pageId/domains/:domainId	status_page:manage

All 4 domain operations — POST …/domains, GET …/domains, POST …/domains/:domainId/refresh, DELETE …/domains/:domainId — require status_page:manage.

Listing domains is the only read on a status page that asks for status_page:manage. Listing components (GET …/components) and listing updates (GET …/updates) are status_page:read, so somebody who can open your page and read its components cannot see the domains attached to it. Which roles hold which of the two permissions is on the status pages page.

If listing domains returns 403 for someone who can otherwise use the status-page screens, this is why, and the answer is a role change rather than a bug report.

A 403 on adding is the one case where that advice can send you the wrong way, because adding is the only domain operation with a second gate on it. Read the body before you touch anybody’s role: a plain forbidden is the permission above, and feature_gated is the plan gate at the top of this page.

Removing a domain

Removing a domain takes that address away and touches nothing else. The page stays where it was, the slug URL is unaffected and still serves, and the domain stops resolving to your page. It is not a way to unpublish — if you want the page off the internet, unpublish the page.

The name goes back to being unclaimed, so you can add it again later, or to a different page.