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

# Notifications

> Integrate Soundcheck with the Backstage Notifications plugin for check status and certification change alerts, replacing legacy Slack and email notifications.

Soundcheck integrates with the [Notifications plugin](https://backstage.io/docs/notifications/) by providing a number of built in notifications.

## Setup

Install the notifications plugin for Backstage per the [instructions here](https://backstage.io/docs/notifications/#installation).

In soundcheck enable notifications globally with the following setting:

```yaml theme={"theme":{"light":"github-light","dark":"dracula"}}
soundcheck:
  notifications:
    enabled: true
```

### Migrating from Legacy Soundcheck Notifications

<Warning>
  The legacy campaign notification systems — direct Slack integration and direct
  email (SMTP) integration — are **deprecated** and will be removed in a future
  release. Migrate to the Backstage Notifications plugin as described below.
</Warning>

#### What is deprecated

**Direct Slack notifications** — The `soundcheck.slack` configuration block and the `supportChannel` field on campaigns are deprecated. These power direct Slack message delivery via the `SlackNotificationService`.

```yaml theme={"theme":{"light":"github-light","dark":"dracula"}}
# Deprecated
soundcheck:
  slack:
    token: ${SLACK_OAUTH_TOKEN}
    appToken: ${SLACK_APP_TOKEN}
    signingSecret: ${SLACK_SIGNING_SECRET}
```

**Direct email notifications** — The `soundcheck.email` configuration block is deprecated. This powers direct SMTP email delivery via the `EmailNotificationService`.

```yaml theme={"theme":{"light":"github-light","dark":"dracula"}}
# Deprecated
soundcheck:
  email:
    host: smtp.example.com
    port: 587
    from: soundcheck@example.com
    auth:
      user: ${SMTP_USER}
      pass: ${SMTP_PASS}
```

#### Migration steps

1. Enable the Backstage Notifications plugin: set `soundcheck.notifications.enabled: true`
2. Remove the `soundcheck.slack` and `soundcheck.email` configuration blocks
3. The `supportChannel` field on campaigns will be ignored once the legacy systems are removed
4. Install email or slack processors as indicated in the [Backstage documentation](https://backstage.io/docs/notifications/processors#built-in-processors).

See the [Backstage Notifications documentation](https://backstage.io/docs/notifications/) for more information.

#### Replacement

The Backstage Notifications plugin provides a unified notification system that supports multiple delivery channels (in-app, Slack, email, etc.) through Backstage notification modules. All [campaign notifications](./campaigns#campaign-notifications) are supported in the Backstage Notifications plugin integration.

#### Differences between legacy and new system

1. The new system integrates directly with the open source notifications plugin and benefits from the features there.
2. The new system has additional notification types, and enhanced campaign notifications.
3. Any new features around notifications will only work with the new notification system.
4. Email and Slack are no longer configured within Soundcheck and as part of the campaign fields, but within the notification processors.

## Notification Allowlist

By default, when `soundcheck.notifications.enabled` is `true`, all checks, tracks, and campaigns trigger notifications. You can configure an optional allowlist to limit notifications to specific items.

### Configuration

Add an `allowlist` under `soundcheck.notifications` in your `app-config.yaml`:

```yaml theme={"theme":{"light":"github-light","dark":"dracula"}}
soundcheck:
  notifications:
    enabled: true
    allowlist:
      checks:
        - has-readme
        - has-owner
      tracks:
        - micro-certified
      campaigns:
        - q2-reliability-push
```

### Behavior

* When `allowlist` is **not configured**, all items trigger notifications (backwards-compatible).
* The `checks`, `tracks`, and `campaigns` lists are **independent**. If only `checks` is specified, only check notifications are filtered; track and campaign notifications continue for all items.
* When an allowlist is specified for a type (e.g., `checks`), only items whose IDs appear in that list generate notifications. For example, with the configuration above, a failing check with ID `has-readme` triggers a notification, but a failing check with ID `has-tests` does not.
* An **empty array** (e.g., `checks: []`) blocks all notifications of that type.
* For campaigns and milestones, the allowlist gates **all notification channels** (Backstage notifications, Slack, and email). For checks and tracks, it only gates Backstage notifications since these don't send Slack/email notifications.

## Notification Types

This documents notifications that Soundcheck will send. To build more robust or complex notifications involving Soundcheck, we suggest looking at [events](./events).

### Campaigns

* **Campaign Create** - owner of Campaign
* **Campaign Updated** - owner of Campaign
* **Campaign Archived** - owner of Campaign
* **Campaign Deleted** - owner of Campaign
* **Campaign Milestone Reached** - owner of Campaign

### Checks

* **Previously Passing Check is now Failing** - owner of entities that are failing this check. If multiple entities a user owns are failing a check, only 1 notification is sent. This only triggers if the previous check state was passed.

### Tracks

* **Previously Certified Track is now Failing** - owner of entities that are failing certification. If multiple entities a user owns are failing certification, only 1 notification is sent. This only triggers if the previous certification state was passed.
* **Previously Passing Campaign is now Failing** - owner of entities that are failing this campaign. If multiple entities a user owns are failing this campaign, only 1 notification is sent. This only triggers if the previous campaign state was passed.