Configure outbound webhooks

Outbound webhooks deliver Observer events to an HTTPS endpoint as JSON. They are the integration path for paging tools, ticketing systems, and chat notifications.

Available event types

Incident events

Type	Trigger
`incident.created`	A new incident is created (draft or published).
`incident.updated`	An incident's title, severity, affected services, or visibility changes.
`incident.published`	A draft incident is published and becomes visible on the public page.
`incident.resolved`	An incident is resolved.
`incident.deleted`	An incident is deleted.
`incident.message_added`	A new message is appended to an incident timeline.
`incident.auto_drafted`	The auto-incident worker creates a draft from an unhealthy metric flip.
`incident.auto_published`	An auto-drafted incident is published.
`incident.auto_dismissed`	An auto-drafted incident is dismissed or expires with no action.

Maintenance events

Type	Trigger
`maintenance.scheduled`	A maintenance window is created.
`maintenance.starting_soon`	A scheduled maintenance window is within the next hour.
`maintenance.started`	A maintenance window starts.
`maintenance.completed`	A maintenance window completes.
`maintenance.canceled`	A maintenance window is canceled before completion.

Metric and agent events

Type	Trigger
`metric.status_changed`	A metric's status flips after dwell gating.
`metric.no_data`	A metric enters `no_data` because the agent could not collect a sample.
`agent.offline`	An agent misses its expected heartbeat window.

Configure a subscription

•
Create the subscription
In the console, open Webhooks, then New subscription. Configure:
- Endpoint URL: an HTTPS endpoint that accepts POST requests with a JSON body. HTTP is rejected.
- Signing secret: optional shared secret. When set, Observer signs every delivery with HMAC-SHA-256 in the X-Observer-Signature header.
- Event types: tick the events the endpoint should receive.
Save the subscription. The first delivery confirms reachability.
Verify deliveries
The subscription detail page lists recent deliveries with their HTTP response code and round-trip time. Successful deliveries return a 2xx response within the timeout window. Failed deliveries are retried with exponential backoff.
•
Verify the signature (recommended)
When a signing secret is set, every delivery includes three headers:
```
X-Observer-Signature:        sha256=<hex>
X-Observer-Signature-Legacy: sha256=<hex>
X-Observer-Timestamp:        <unix-millis>
```
The signed material for X-Observer-Signature is ${timestamp}.${rawBody}. To verify (recommended):
1. Read X-Observer-Timestamp. Reject the delivery if it is more than five minutes from the current time on the receiver. This skew window bounds replay attacks against captured deliveries.
2. Compute HMAC-SHA-256(secret, "${timestamp}.${rawBody}") and hex-encode the digest. Prepend sha256=.
3. Compare against X-Observer-Signature using a constant-time comparison (crypto.timingSafeEqual in Node, hmac.compare_digest in Python, equivalents elsewhere). String equality leaks information through timing side channels.
Reject deliveries whose signatures do not match.
Legacy header
X-Observer-Signature-Legacy carries HMAC-SHA-256(secret, rawBody) for receivers that have not migrated to the timestamp-prefixed scheme. It is sent for one release cycle then dropped. Use the timestamp-prefixed X-Observer-Signature for new integrations; receivers relying on X-Observer-Signature-Legacy lose replay protection.

Quotas

Webhook subscription quotas vary by plan. Endpoints over the cap on a downgrade remain configured; new endpoints are blocked until the plan is upgraded or an existing endpoint is removed.

Payload reference

See the webhook payload reference for the JSON shape of each event type.