# Notification webhooks

What an alarm, an uptime check and a status page POST to a webhook, and what counts as delivered.

## Where a webhook may point

A webhook URL is `https://` on the default port 443, without a user name or password, up to 2048
characters. Every address its host resolves to must be public, and the request goes to the address
that was checked. A URL that breaks one of the rules that need no lookup is refused when you save it
with `400`; the message is the field name (`webhookUrl`, or `target` for a status page subscriber),
then "Webhook URL: only https:// URLs are fetched" or the rule it broke. A host name that resolves to a private address is only found when a
notification is sent, and that notification fails.

## Delivery

Each notification is one JSON `POST`, with `content-type: application/json`. A `2xx` answer within
5 seconds counts as delivered. Any other status, a redirect (it is not followed), a host that
resolves to a private address or no answer is a failure. A failure is not retried; it is recorded
where the notification is: in the alarm's history, in the check's outage log, or in the
`notified` summary of an incident post. A failed status page webhook for a component going down or
up is not recorded where you can read it.

## Alarm state change

```json
{
  "type": "ews.monitoring.alarm.state-change",
  "alarm": {
    "id": "…",
    "name": "web-1 CPU high",
    "resourceType": "instance",
    "resourceId": "i-1a2b3c4d",
    "metric": "cpu_percent",
    "statistic": "avg",
    "comparator": ">",
    "threshold": 80,
    "periodSeconds": 300,
    "evaluationPeriods": 3
  },
  "previousState": "OK",
  "state": "ALARM",
  "reason": "Threshold crossed: 3 datapoint(s) [91.20, 95.00, 97.40] were greater than the threshold (80).",
  "at": "2026-10-29T12:08:00.000Z"
}
```

An alarm on a custom series also carries `alarm.dimensions`. It is sent on entering and on leaving
`ALARM` only.

## Uptime check down or up

```json
{
  "type": "ews.monitoring.uptime.state-change",
  "check": { "id": "…", "name": "Shop", "url": "https://shop.example.com/health" },
  "state": "DOWN",
  "reason": "…",
  "at": "2026-10-29T12:08:00.000Z",
  "downSince": null,
  "failedLocations": ["control-plane", "…"]
}
```

`state` is `DOWN` or `UP`. On `UP`, `downSince` is when the outage started.

## Status page events

A webhook subscriber of a status page gets a `type` of
`ews.monitoring.status-page.incident.created`, `….incident.updated` or `….incident.resolved`, with
`incident` (its id, title, impact, status, start, end and newest update), or
`ews.monitoring.status-page.component.down` or `….component.up`, with `component` (id and name),
`state` and `reason`. Every one carries `page` (id, slug, title, url) and `at`.

## Related

- [How alarms work](how-alarms-work.md)
- [How uptime checks work](how-uptime-checks-work.md)
- [Manage subscribers](manage-subscribers.md)
