Notification webhooks

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

Last updated 18 November 2026View as Markdown

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

{
  "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

{
  "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.

Did this page help you?