Skip to main content

Notifications

Notifications help you stay connected with Skill Exchange by alerting you of requests and updates. Whether you're a mentor sharing knowledge, a learner seeking guidance, or a hack project participant, notifications ensure you never miss opportunities to engage and collaborate.

Skill Exchange supports notifications through two channels:

Backstage Notifications​

Skill Exchange integrates with Backstage's built-in notification plugin to deliver notifications directly within your Backstage instance.

Prerequisites​

Before configuring Skill Exchange notifications, you must install the Backstage notifications plugin. Follow the official installation guide to set up the plugin in your Backstage instance.

Configuration​

Once the notifications plugin is installed, enable Skill Exchange notifications by adding the following configuration to your app-config.yaml:

app-config.yaml
skillExchange:
  # ...
  notifications:
    enabled: true
  # ...

Slack Notifications​

For teams that prefer Slack-based notifications, Skill Exchange can send direct messages to Slack users. This requires setting up a custom Slack app with specific permissions.

Prerequisites​

Before configuring Slack notifications, you'll need:

  • Admin access to your Slack workspace
  • Ability to create and configure Slack apps
  • The following Slack app credentials:
    • OAuth Token
    • App Token
    • Signing Secret

Step 1: Create a Slack App​

  1. Go to api.slack.com/apps
  2. Click "Create New App"
  3. Choose "From scratch"
  4. Enter app name: Skill Exchange for Backstage
  5. Select your workspace

Step 2: Configure App Settings​

Enable Socket Mode​

  1. In your Slack app dashboard, go to "Settings" → "Socket Mode"
  2. Toggle "Enable Socket Mode" to On
  3. Create an app-level token with the connections:write scope
  4. Save the generated app token (starts with xapp-)

Configure OAuth & Permissions​

  1. Go to "OAuth & Permissions" in the sidebar
  2. Add the following bot token scopes:
    • users:read - Read user information
    • users:read.email - Read user email addresses
    • im:write - Open direct messages with users
    • chat:write - Send messages as the app
    • chat:write.public - Send messages to public channels

Step 3: Install the App​

  1. Go to "Install App" in the sidebar
  2. Click "Install to Workspace"
  3. Authorize the app with the requested permissions
  4. Copy the "Bot User OAuth Token" (starts with xoxb-)

Step 4: Get Your Signing Secret​

  1. Go to "Basic Information" in the sidebar
  2. Scroll down to "App Credentials"
  3. Copy the "Signing Secret"

Step 5: Configure Skill Exchange​

Add your Slack credentials to your app-config.yaml:

app-config.yaml
skillExchange:
  # ...
  slack:
    token: xoxb-*************-*************-************************ # Bot User OAuth Token
    appToken: xapp-*-***********-*************-**************************************************************** # App-Level Token
    signingSecret: ******************************** # Signing Secret
  # ...

Alternative: Use App Manifest​

Instead of manually configuring the app, you can use the provided manifest file to create your Slack app with all required settings:

slack-app-manifest.yml
# This file is an example Slack app manifest used for installing a custom app in your workspace to deliver
# Skill Exchange notifications. For more information, see https://api.slack.com/reference/manifests#creating_apps
display_information:
  name: Skill Exchange for Backstage
  description: Enables notifications from Skill Exchange for Backstage in Slack.
  background_color: '#9BF0E1'
features:
  bot_user:
    display_name: Skill Exchange for Backstage
    always_online: true
oauth_config:
  scopes:
    bot:
      # scopes needed to read user information
      - users:read
      - users:read.email
      # scope needed to open DMs to users
      - im:write
      # scopes needed to send messages
      - chat:write
      - chat:write.public
settings:
  interactivity:
    is_enabled: true
  org_deploy_enabled: false
  socket_mode_enabled: true
  token_rotation_enabled: false

To use this manifest:

  1. Go to api.slack.com/apps
  2. Click "Create New App"
  3. Choose "From an app manifest"
  4. Select your workspace
  5. Paste the manifest content above
  6. Follow the installation steps to get your tokens

Troubleshooting​

Common Issues:

  • "Invalid token": Ensure you're using the Bot User OAuth Token, not the App-Level Token
  • "Missing scopes": Verify all required scopes are added to your Slack app
  • "Socket mode disabled": Enable Socket Mode in your app settings
  • "Messages not sending": Check that the app is installed to your workspace

For additional help, refer to the Slack API documentation or check your Backstage logs for detailed error messages.

Customizing Notification Messages​

Skill Exchange allows you to customize notification messages to match your organization's communication style and terminology. You can tailor the content, formatting, and tone of notifications for both Backstage's Notifications and Slack channels.

For detailed instructions on customizing notification messages, including code examples and best practices, see the Customizing Skill Exchange Notifications documentation.