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

# Notifications

# Notifications

Svantic delivers real-time notifications whenever an alert subscription or policy triggers. Whether an agent registers or deregisters, a request needs human approval, or a platform event fires, the system pushes context through the channels you configure.

## How it works

Every **alert subscription** (or **policy**) can link to one or more **notification channels**. When the subscription's event type matches an incoming event, Svantic evaluates the subscription and — if it has linked channels — delivers a notification through each enabled one.

**Event ingested → Subscription matched → Channels notified → In-app notification created**

All notifications also appear in the **dashboard notification center** (bell icon in the top bar), regardless of external channel configuration.

## Notification channels

A channel is a configured delivery endpoint. Svantic supports three channel types:

| Type        | Delivers to               | Configuration                     |
| ----------- | ------------------------- | --------------------------------- |
| **Webhook** | Any HTTP endpoint         | URL                               |
| **Slack**   | Slack channel via Bot API | Bot Token + Channel ID            |
| **Email**   | Inbox                     | Recipient email addresses (array) |

Channels are tenant-scoped and reusable — the same channel can be linked to multiple alert subscriptions or policies.

### Webhook

Delivers a JSON payload to any HTTP endpoint. Useful for integrating with PagerDuty, Opsgenie, custom automation, or ticketing systems.

```json theme={null}
{
  "type": "webhook",
  "name": "PagerDuty",
  "config": {
    "url": "https://events.pagerduty.com/integration/..."
  }
}
```

### Slack

Delivers formatted Block Kit messages to a Slack channel using the Slack Web API (`chat.postMessage`). Requires a Slack App with a **Bot Token** and a **Channel ID**.

```json theme={null}
{
  "type": "slack",
  "name": "Engineering alerts",
  "config": {
    "bot_token": "xoxb-...",
    "channel_id": "C0123456789"
  }
}
```

See the [Slack setup guide](#slack-setup-guide) below for step-by-step instructions on obtaining these values.

### Email

Delivers formatted HTML emails via the Resend transactional email service. Recipients are stored as an array of email addresses.

```json theme={null}
{
  "type": "email",
  "name": "Ops team",
  "config": {
    "recipients": ["ops@company.com", "oncall@company.com"]
  }
}
```

When entering recipients in the dashboard, use a comma-separated list (e.g., `ops@company.com, oncall@company.com`). The system splits and trims them automatically.

## Alert subscriptions

Alert subscriptions define which platform events trigger notifications. Each subscription maps to a specific event type and can be enabled or disabled independently. Svantic seeds a default set of subscriptions for every tenant.

### Default alert subscriptions

| Event Type             | Category       | Default Severity |
| ---------------------- | -------------- | ---------------- |
| `agent.registered`     | Infrastructure | info             |
| `agent.deregistered`   | Infrastructure | warning          |
| `agent.health_changed` | Infrastructure | critical         |
| `agent.connected`      | Infrastructure | info             |
| `agent.disconnected`   | Infrastructure | warning          |
| `agent.flagged`        | Governance     | critical         |
| `auth.token_issued`    | Governance     | info             |
| `dispatch.failed`      | Sessions       | warning          |
| `session.error`        | Sessions       | warning          |

### Linking channels to subscriptions

Each subscription can have multiple channels attached. In the dashboard, navigate to **Alerts** and click **Add channel** on any subscription. Select the channel type, enter the configuration, and toggle it on.

Via the API:

```json theme={null}
POST /internal/alerts/add_channel
{
  "subscription_id": "sub-uuid",
  "type": "slack",
  "config": {
    "bot_token": "xoxb-...",
    "channel_id": "C0123456789"
  },
  "enabled": true
}
```

### No cooldown

Alert subscriptions fire on **every matching event** without suppression. If an agent registers five times, the subscription triggers five notifications. This ensures no events are silently dropped.

## In-app notifications

Every triggered alert creates an in-app notification visible in the dashboard:

* **Bell icon** (top bar) — shows unread count badge and a dropdown of recent notifications
* **Notifications page** — full paginated list with mark-as-read controls
* **Sidebar** — displays total unread count

Marking a notification as read (individually or all at once) updates the count across all dashboard components in real time.

## Notification payload

Every notification includes:

* **Rule name** — which alert subscription or policy triggered
* **Severity** — info, warning, or critical
* **Event data** — agent type, instance ID, session details, or other context
* **Timestamp** — when the event occurred

Webhook notifications deliver this as a JSON POST body. Slack notifications use Block Kit formatting with severity-coded emoji indicators. Email notifications use formatted HTML.

## Managing channels

Channels are managed in the dashboard under **Settings → Channels**, or via the API:

* `POST /internal/channels/get` — list all channels for the tenant
* `POST /internal/channels/new` — create a channel
* `POST /internal/channels/update` — update a channel
* `POST /internal/channels/delete` — delete a channel

## Slack setup guide

Follow these steps to create a Slack App and obtain the **Bot Token** and **Channel ID** required for Slack notifications.

### 1. Create a Slack App

1. Go to [api.slack.com/apps](https://api.slack.com/apps) and click **Create New App**
2. Choose **From scratch**
3. Enter a name (e.g., "Svantic Alerts") and select your workspace
4. Click **Create App**

### 2. Add bot scopes

1. In the left sidebar, click **OAuth & Permissions**
2. Scroll to **Bot Token Scopes**
3. Click **Add an OAuth Scope** and add `chat:write`

### 3. Install to workspace

1. Scroll back up on the **OAuth & Permissions** page
2. Click **Install to Workspace** (or **Request to Install** if your workspace requires admin approval)
3. Click **Allow** on the permission prompt
4. Copy the **Bot User OAuth Token** — this is your `bot_token` (starts with `xoxb-`)

<Note>
  If you see "Request to Install" instead of "Install to Workspace", your workspace has app approval enabled. Ask a workspace admin to approve the app, or temporarily disable app approval in Slack Admin → Manage Apps → Settings.
</Note>

### 4. Get the Channel ID

1. In Slack, navigate to the channel where you want alerts delivered
2. Right-click the channel name → **View channel details**
3. Scroll to the bottom of the details panel
4. Copy the **Channel ID** (e.g., `C0123456789`)

### 5. Invite the bot

In the target Slack channel, type:

```
/invite @Svantic Alerts
```

Replace "Svantic Alerts" with the name you gave your app in step 1. The bot must be a member of the channel to post messages.

### 6. Configure in Svantic

In the Svantic dashboard:

1. Go to **Settings → Channels** → click **New Channel**
2. Select **Slack** as the type
3. Enter a name (e.g., "Engineering Slack")
4. Enter the **Bot Token** (`xoxb-...`)
5. Enter the **Channel ID** (`C0123456789`)
6. Click **Create**

Or add a Slack channel directly on the **Alerts** page by clicking **Add channel** on any subscription and selecting Slack.

### Troubleshooting

| Problem                          | Solution                                                                                                         |
| -------------------------------- | ---------------------------------------------------------------------------------------------------------------- |
| `missing_scope` error            | Add `chat:write` scope in OAuth & Permissions, then reinstall the app to your workspace. Copy the new bot token. |
| `invalid_auth` error             | The bot token is incorrect or expired. Reinstall the app and copy the fresh token.                               |
| `channel_not_found` error        | The Channel ID is wrong, or the bot hasn't been invited to the channel.                                          |
| `not_in_channel` error           | Invite the bot: `/invite @YourBotName` in the target channel.                                                    |
| No "Install to Workspace" button | Your workspace requires admin approval. Ask an admin or disable approval in Slack Admin settings.                |

## Next steps

* [Channels guide](/guides/channels) — detailed reference for all channel types and templates
* [Slack Integration guide](/guides/slack-integration) — bidirectional Slack setup with interactive approval buttons
* [Policies guide](/guides/policies) — create and manage unified policies