> ## Documentation Index
> Fetch the complete documentation index at: https://docs.squasher.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Notifications API

> Manage notification destinations, routes, and inspect delivery history.

Use the Notifications API to manage where incidents go and which destinations
fire on which conditions. The retired `alerts.*` operations were folded into
this surface — destinations replace alert rule channel configs, routes
replace alert rule trigger conditions, and a single test-send endpoint
exercises the same outbound path real notifications take.

## Operations

| Operation                            | Method and path                                                                   | Purpose                                                                        |
| ------------------------------------ | --------------------------------------------------------------------------------- | ------------------------------------------------------------------------------ |
| `notifications.listDestinations`     | `GET /v1/projects/{project_id}/notifications/destinations`                        | List Slack/webhook/email/PagerDuty destinations for a project.                 |
| `notifications.createDestination`    | `POST /v1/projects/{project_id}/notifications/destinations`                       | Create a destination. Webhooks require a public HTTPS URL.                     |
| `notifications.deleteDestination`    | `DELETE /v1/projects/{project_id}/notifications/destinations/{destination_id}`    | Delete a destination.                                                          |
| `notifications.testDestination`      | `POST /v1/projects/{project_id}/notifications/destinations/{destination_id}/test` | Send a test notification by writing one outbox row that the worker dispatches. |
| `notifications.listRoutes`           | `GET /v1/projects/{project_id}/notifications/routes`                              | List routes — scope, conditions, behavior, attached destination ids.           |
| `notifications.createRoute`          | `POST /v1/projects/{project_id}/notifications/routes`                             | Create a route with one or more destination ids.                               |
| `notifications.setRouteDestinations` | `PUT /v1/projects/{project_id}/notifications/routes/{route_id}/destinations`      | Replace the set of destinations attached to a route.                           |
| `notifications.deleteRoute`          | `DELETE /v1/projects/{project_id}/notifications/routes/{route_id}`                | Delete a route.                                                                |
| `notifications.listDeliveries`       | `GET /v1/projects/{project_id}/notifications/deliveries`                          | List recent delivery attempts — success and failure — for the project.         |

Destination configs are type-specific:

* `slack` — `{ channelId, channelName }`, plus `integrationId` pointing at the connected Slack OAuth row.
* `webhook` — `{ url, secret? }`. `url` must use public HTTPS. Secret enables
  `X-Squasher-Signature` HMAC SHA-256 on the request body. At delivery time,
  Squasher rejects private or reserved DNS results, pins the TLS connection to
  a validated public address, refuses redirects, and applies a 10-second
  timeout.
* `email` — `{ recipients: string[] }`, max 20.
* `pagerduty` — `{ integrationKey, severityMap? }`.

Route behavior supports one setting: `includeAiSummary?: boolean`. When it is
`false`, AI-derived incident sections are omitted from the initial delivery and
every retry. Cooldown belongs to monitor incident creation, not notification
routing; notification-route cooldown and update-grouping fields are rejected.

Route conditions support `attentionClasses?: ("interrupt" | "digest")[]`.
Omitting the field matches both classes. An active, expiring monitor-tuning
override can route that monitor's incident events as `digest` while leaving
the incident severity unchanged; reverting or expiring the override restores
`interrupt`. Configure a matching digest route before applying the proposal.

Responder rotations live in the [On-call API](/api-reference/on-call). Use
`onCall.getCurrentEngineer` or `onCall.listShifts` when an agent needs to
explain who is currently covering a project before changing notification routes.

Secret fields (webhook secret, PagerDuty integration\_key, Slack bot token)
are write-only — `GET` responses return a redacted `••••<last4>` preview
under `configPreview`. Webhook previews contain only the URL origin; path,
query, and credential material are never returned.

## Webhook payload

Webhook destinations receive a JSON `POST` with this shape:

```json theme={null}
{
  "event": "opened",
  "incident_id": "11111111-1111-4111-8111-111111111111",
  "project_id": "22222222-2222-4222-8222-222222222222",
  "title": "API: 500 Error Rate Spike",
  "severity": {
    "key": "sev-1",
    "label": "SEV-1",
    "rank": 1
  },
  "sent_at": "2026-05-16T07:00:37.123Z"
}
```

* `event` is a `NotificationLifecycleEvent`: `opened`, `acknowledged`,
  `resolved`, `status_changed`, or `public_update`. `status_changed` comes
  from explicit incident status changes, while public status-page notes emit
  `public_update`.
* `severity.label` reflects the project's notation — `SEV-1` by default,
  `P1` when the project's `severity_naming_style` is `p`, or a custom
  rename. Use `severity.key` (always `sev-N`) and `severity.rank` (1–N)
  for stable routing on the consumer side.
* `severity` is `null` when the incident has no resolved severity (e.g.
  test sends without an incident row).
* When a destination secret is set, the same JSON body is signed with
  HMAC SHA-256 and the hex digest is sent in `X-Squasher-Signature`.

## Auth

Every operation is project-scoped and authenticated. Required scope:
`notifications:read` for the four list/get endpoints, `notifications:write`
for the rest. Both are covered by the `*` wildcard and `write` global
shortcuts on an API key.

## CLI and MCP

The CLI doesn't expose a `squasher notifications` subcommand by design —
routing config is configured through the dashboard or via the
`@squasher-ai/api-client` SDK (`client.notifications.*`). In MCP Code Mode,
use `search("notifications")` before `execute`, and ask for confirmation
before creating, updating, deleting, or sending a test notification.

## Agent handoff

```text theme={null}
Audit Squasher notification routing for project <project_id>. List
destinations, routes, and recent deliveries. Recommend the smallest
change. Do not create, update, delete, or send a test until the user
confirms the exact destination_id / route_id and payload.
```

Related: [Notifications](/features/alerts), [Incidents API](/api-reference/incidents).