Skip to main content

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.

Soundcheck integrates with the Notifications plugin by providing a number of built in notifications.

​
Setup

Install the notifications plugin for Backstage per the instructions here. In soundcheck enable notifications globally with the following setting: 
soundcheck:
  notifications:
    enabled: true

​
Migrating from Legacy Soundcheck Notifications

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.

​
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. 
# 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. 
# 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
See the Backstage Notifications documentation 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 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: 
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.

​
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.