# Notifications

Get a signed webhook from Ensue when a destination breaks, backs up or needs a person.

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:

```bash
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](/gateway/circuit-breaker/) opened and sending to it is paused. |
| `destination.breaker_closed` | A probe succeeded and sending resumed. |
| `destination.group_backlog` | A [delivery group](/gateway/delivery-groups/)'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](/agents/wake-hooks/). |
| `test` | You sent one from Settings. |

## Payload

```json
{
  "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](/gateway/flows/) that receives them from a source of your own.