Webhooks

Webhooks allow the Server Monitor to push events to your endpoint when incidents or maintenance change. Configure webhook URLs in the monitoring dashboard; this page describes event types and payloads.

Event types

Typical events (exact names may depend on implementation):

• incident.created — A new incident was opened.
• incident.updated — An incident was updated (e.g. new status update).
• incident.resolved — An incident was resolved/closed.
• maintenance.scheduled — A maintenance window was scheduled.
• component.status_changed — A monitor/component changed status (e.g. up → down).

Payload example

Example webhook POST body (structure may vary):

{
  "event": "incident.created",
  "timestamp": "2026-02-07T12:00:00Z",
  "data": {
    "id": 1,
    "monitor_id": 1,
    "monitor_name": "Web Server",
    "title": "Elevated latency",
    "started_at": "2026-02-07T10:00:00Z"
  }
}

Signature verification

TODO: If the webhook system supports signing (e.g. HMAC in a header), document the header name, algorithm, and how to verify the payload here. Until then, treat webhooks as best-effort and validate using your own checks (e.g. idempotency keys).

Retry policy and idempotency

Your endpoint may receive the same event more than once due to retries. Recommended:

• Respond with 200 OK as soon as you have accepted the payload (e.g. queued for processing) so the provider does not retry unnecessarily.
• Use an id or event_id (if present) as an idempotency key: ignore duplicates before performing side effects.
• Implement exponential backoff if you call external services from your handler; avoid long-running work in the request.