Notifications

You should not have to watch a dashboard to know that a destination is down. Set a notification URL for your workspace and Ensue will POST a signed JSON notice to it when something needs a person.

Set it up

Open Settings → Notifications and enter a URL, or:

curl -X PATCH https://api.getensue.com/v1/workspace/notifications \
  -H "authorization: Bearer ens_<key>" -H "content-type: application/json" \
  -d '{ "url": "https://ops.example.com/ensue-alerts" }'

A signing secret is created the first time you set a URL. GET /v1/workspace/notifications returns both. Send a test notice (POST /v1/workspace/notifications/test) sends a test notification and reports your endpoint’s answer.

Notices

type	Sent when
destination.breaker_opened	A destination’s circuit breaker opened and sending to it is paused.
destination.breaker_closed	A probe succeeded and sending resumed.
destination.group_backlog	A delivery group’s oldest unsent event has waited 15 minutes. The groups are listed; one notice per destination until they catch up.
destination.group_backlog_cleared	Every group of that destination has caught up.
events.failures_piling_up	A burst of events failed within a few minutes. At most one notice an hour per workspace.
inbox.wake_suspended	Loop protection stopped waking an agent until a person resumes it. See Wake hooks.
test	You sent one from Settings.

Payload

{
  "id": "…",
  "type": "destination.breaker_opened",
  "workspace_id": "ws_…",
  "created_at": 1767225600000,
  "data": { … }
}

The data object depends on the type and names the destination, inbox or events involved.

Verify the signature

Notices are signed like Gateway deliveries. The x-ensue-signature header is t=<timestamp>,v1=<hex>, the hex HMAC-SHA256 of "<timestamp>.<body>" using the workspace’s notification secret. Verify it with the raw body and reject old timestamps.

Good to know

• Delivery of a notice is best effort: one try, and failures are logged. The same facts are always on the event timeline and in the dashboard.
• A notice reports a change. Your handler should be quick, return 2xx, and do its own paging.
• Forward notices to Slack or PagerDuty with a small relay, or a Gateway flow that receives them from a source of your own.