Webhooks

Push status events to your own systems.

What webhooks do

Outgoing webhooks POST lifecycle events to any HTTPS endpoint you control — pipe alerts into Slack, PagerDuty, your own tooling, or a logging pipeline.

Events

Event Fires when
monitor.down A monitor fails its failure threshold (carries status, message, latency, region)
monitor.up A monitor recovers (same fields — pair it with the earlier monitor.down)
test_event You hit Test on a webhook
custom event names Custom events emitted through event rules (POST /status-pages/:id/events/emit)

A webhook with an empty events list receives everything; otherwise it only receives the listed events.

Payload

Generic webhooks receive the raw event envelope:

{
  "user_id": "<uuid>",
  "event": "monitor.down",
  "data": {
    "monitor_id": "<uuid>",
    "monitor_name": "API Gateway",
    "status": "down",
    "message": "HTTP 503",
    "latency": 1432,
    "region": "eu-central"
  }
}
Provider Payload
generic Raw envelope above — build your own consumer
discord {"content": "..."} — post straight to a Discord channel webhook URL
slack {"text": "..."} — Slack incoming-webhook format
telegram {"chat_id", "text", "parse_mode": "Markdown"} — the chat id comes from the webhook secret field

A Discord webhook whose URL is not an https://… URL is treated as a bot integration instead — the Discord bot delivers it (channel embeds + DM fan-out) rather than a plain HTTP POST.

Scoping

  • status_page_id scopes a webhook to one page's events
  • team_only webhooks additionally receive internal-only events (classification: "team_only") that public-facing channels never see
  • alert_channels (JSON map event -> channel) routes different events to different Discord channels

Managing webhooks

Per status page via the dashboard (Alert Setup) or the API:

  • GET /status-pages/:id/alert-setup — configured webhooks
  • POST /status-pages/:id/alert-setup — add a webhook
  • PUT /status-pages/:status_page_id/alert-setup/:id — update
  • DELETE /status-pages/:status_page_id/alert-setup/:id — remove
  • POST /status-pages/:status_page_id/alert-setup/:id/test — send a test delivery

Plus account-level management under /webhooks (list, create, update, delete, test, toggle is_active, toggle team_only).

Delivery behavior

  • HTTPS endpoints only, with SSRF protection on our side
  • Inactive webhooks (is_active: false) are skipped
  • Every delivery attempt is logged in webhook_deliveries — you can inspect exactly what was sent and the response
  • Discord channel sends are deduplicated per event/alert so multi-region flaps don't spam
NextDiscord Bot