Alert webhooks

The payload

Every alert is one JSON POST. event is one of went-down, still-down, recovered, went-slow or back-to-normal. The rest names the page and monitor, the URL, the error, when the outage began, the response time and the slow threshold, and at, the moment of the alert in milliseconds since the epoch.

{
  "event": "went-down",
  "page": "Northwind",
  "monitor": "API",
  "url": "https://api.northwind.example/health",
  "pageUrl": "https://northwind.statoss.com",
  "error": "timeout",
  "downSince": null,
  "latencyMs": 10000,
  "thresholdMs": null,
  "at": 1789456789000
}

The monitor's name also goes out as checkpoint, the field's name before 14 September 2026, so older receivers keep working.

Verifying the signature

The body is signed with HMAC-SHA256 using the secret shown on the settings page and sent as X-StatOSS-Signature: sha256=<hex>. Compute the same HMAC over the raw body, compare with a constant-time comparison, and drop anything that does not match. The event name is repeated in X-StatOSS-Event, so a receiver can route on the header without parsing the body. Answer with any 2xx.

Setting it up

1. Open the page's settings, Alerts, choose Webhook under "Add a destination", paste the URL and save. Loopback, private and link-local addresses are refused, since the request comes from our servers.
2. Copy the secret shown next to it into your receiver.
3. Press "Send a test alert" to get a signed test payload.

The webhook is on Hobby ($4 a month) and Pro. Email alerts are on every plan, Free included. The pricing page has the rest.

Subscribers to a page can take a webhook too, on the Subscribers tab: they get every incident update as signed JSON, which is the way to mirror a page's incidents into another system. The subscribers page has that format.

When an alert goes out

One alert per change of state: when a monitor goes down, when it turns slow, and when it is back, with the time, the reason, and how long it was out. A monitor counts as down after two failed checks in a row, each confirmed by a second server on another network; a single failed check sends nothing. A repeat interval sends a "still down" notice every so many minutes while an outage lasts, and nothing is sent during a maintenance window. Every kind of monitor alerts the same way: a website, an API, a port, a certificate, a cron job.