Webhooks

Overview

A generic webhook sends an HTTP POST to any endpoint whenever a monitor’s status changes. It’s the most flexible way to integrate OKStatus with a tool that has no dedicated channel — and it’s available on every plan, Free included.

Setup

1. Go to Alerting → Channels → Add a channel → Webhook.
2. Enter the destination URL.
3. Optionally set a secret — it is sent back to you on every call so you can reject requests that don’t carry it.
4. Click Test, then attach the channel to your monitors.

The URL must be publicly resolvable: an address that resolves to a private or reserved IP is refused, both when saving the channel and again at send time.

Payload

{
  "event": "monitor.down",
  "monitor": {
    "name": "Main website",
    "url": "https://example.com"
  },
  "region": "fr-dc3",
  "timestamp": "2026-09-09T14:30:00.000Z"
}

The payload is deliberately small and stable. Anything more — HTTP code, latency, uptime — is one authenticated call away on the REST API, keyed by the monitor’s name or URL.

Available events

event	Sent when
monitor.down	The monitor is confirmed down
monitor.degraded	Partial outage, slow response, or a redirect mismatch
monitor.up	The monitor recovered
monitor.paused	The monitor was paused
slo.budget	An SLO burns its budget fast, passes 75 % or runs out

A monitor.degraded sent by a response time alert carries four more fields, so a receiver can route slowness apart from failures: "reason": "latency_threshold", latencyMs (the measured time), thresholdMs (the monitor’s threshold) and slowRegions (the slow region codes). Every other event keeps the payload above, unchanged.

An abnormal latency alert (Max and Enterprise) carries "reason": "latency_anomaly" instead, with latencyMs (the p95 over the last 15 minutes), usualMs ({ "low": …, "high": … }, the usual range at this hour) and slowRegions.

An slo.budget event (Max and Enterprise) carries kind (fast_burn, 75_percent or exhausted), subject (type monitor or group, id, name), target, windowDays (30), budgetMinutes, consumedMinutes, remainingMinutes, exhaustsAt and, for fast_burn, burn (windowMinutes, burnedMinutes).

There is no incident.* event: incidents are something you write, not something the engine detects. Read or create them through the Incidents API.

Security

If you set a secret on the channel, every request carries it verbatim in an X-Webhook-Secret header. Compare it against your own copy and drop the request when it doesn’t match.

Caution

This is a shared secret, not an HMAC signature of the body — there is no X-OKStatus-Signature header to verify. Treat the secret like a password: send it over HTTPS only, and rotate it by editing the channel.

A non-2xx response marks the notification as failed on the alert, visible as a ✗ next to the channel in the Alerts log. OKStatus does not retry the call.