Slack Integration

Table of contents

1. Overview
2. Quick Setup (Incoming Webhooks)
   1. Step 1: Create Webhook in Slack
   2. Step 2: Configure in ButterStack
3. Full Slack App Setup
   1. Step 1: Create Slack App
   2. Step 2: Install App to Workspace
   3. Step 3: Configure OAuth in ButterStack
4. Notification Configuration
   1. Channel Routing
   2. Message Formatting
   3. Notification Templates
5. Slash Commands
   1. /butterstack status
   2. /butterstack build
   3. /butterstack approve
   4. /butterstack help
6. Interactive Features
   1. Approval Workflows
   2. Build Controls
7. Advanced Configuration
   1. Thread Notifications
   2. Custom Workflows
   3. Analytics Integration
8. Troubleshooting
9. Best Practices
10. Integration Examples
    1. Python Webhook Example
11. Related

Overview

Connect ButterStack to Slack for instant notifications about builds, asset updates, and team collaboration. This integration supports both incoming webhooks and full Slack app functionality.

Quick Setup (Incoming Webhooks)

The fastest way to get started is with incoming webhooks for basic notifications.

Step 1: Create Webhook in Slack

1. Go to api.slack.com/apps
2. Click Create New App → From scratch
3. Name it “ButterStack” and select your workspace
4. Go to Incoming Webhooks → Enable
5. Click Add New Webhook to Workspace
6. Select the channel for notifications
7. Copy the webhook URL

Step 2: Configure in ButterStack

1. Navigate to Settings → Integrations
2. Click Add Integration → Slack
3. Paste the webhook URL
4. Select notification types:
   • ✅ Build completions
   • ✅ Asset approvals needed
   • ✅ Task assignments
   • ✅ Error alerts

Copy Webhook Format

Full Slack App Setup

For interactive features and slash commands, create a full Slack app.

Step 1: Create Slack App

1. Visit api.slack.com/apps
2. Click Create New App → From manifest
3. Paste this manifest:

display_information:
  name: ButterStack
  description: Asset pipeline and build management
  background_color: "#5D5DFF"
  
oauth_config:
  scopes:
    bot:
      - channels:read
      - chat:write
      - commands
      - users:read
      
settings:
  interactivity:
    is_enabled: true
    request_url: https://app.butterstack.com/slack/interactive
  event_subscriptions:
    request_url: https://app.butterstack.com/slack/events
    bot_events:
      - app_mention
      - message.channels
  org_deploy_enabled: false
  socket_mode_enabled: false
  
features:
  bot_user:
    display_name: ButterStack
    always_online: true
  slash_commands:
    - command: /butterstack
      url: https://app.butterstack.com/slack/commands
      description: Interact with ButterStack
      usage_hint: "[status|build|approve] [options]"

Copy Manifest

Step 2: Install App to Workspace

1. Go to OAuth & Permissions
2. Click Install to Workspace
3. Review and approve permissions
4. Copy the Bot User OAuth Token

Step 3: Configure OAuth in ButterStack

1. In ButterStack, go to Settings → Integrations → Slack
2. Switch to OAuth App mode
3. Enter:
   • Bot Token: xoxb-your-token
   • Signing Secret: (from Basic Information)
   • Default Channel: #butterstack

Notification Configuration

Channel Routing

Route different notifications to specific channels:

Build Success: #butterstack-builds
Build Failure: #butterstack-alerts
Asset Approval: #butterstack-approvals
Task Assignment: #butterstack-tasks
System Errors: #butterstack-critical

Message Formatting

Customize notification appearance:

Notification Templates

Configure custom templates:

{
  "build_success": {
    "color": "good",
    "title": "✅ Build #{build_number} Completed",
    "fields": [
      {"title": "Project", "value": "{project_name}", "short": true},
      {"title": "Duration", "value": "{duration}", "short": true}
    ],
    "actions": [
      {"text": "View Build", "url": "{build_url}"},
      {"text": "Download", "url": "{artifact_url}"}
    ]
  }
}

Slash Commands

Available commands after full app setup:

/butterstack status

Check system and project status

/butterstack status [project-name]

/butterstack build

Trigger or check builds

/butterstack build start MyGame linux
/butterstack build status 123
/butterstack build list --limit 5

/butterstack approve

Approve pending assets

/butterstack approve asset-123
/butterstack approve --list

/butterstack help

Show all available commands

Interactive Features

Approval Workflows

Enable direct approvals from Slack:

Build Controls

Start and manage builds:

// Triggered by: /butterstack build start MyGame linux
{
  "response_type": "in_channel",
  "blocks": [
    {
      "type": "section",
      "text": {
        "type": "mrkdwn",
        "text": "🚀 *Build Started*\nProject: MyGame\nPlatform: Linux"
      }
    },
    {
      "type": "actions",
      "elements": [
        {
          "type": "button",
          "text": {"type": "plain_text", "text": "Cancel Build"},
          "action_id": "cancel_build",
          "value": "build_123"
        }
      ]
    }
  ]
}

Advanced Configuration

Thread Notifications

Group related notifications in threads:

Thread Grouping:
  - Build start → Updates → Completion
  - Asset upload → Analysis → Approval
  - Task creation → Assignment → Completion

Custom Workflows

Create Slack workflows that integrate with ButterStack:

1. Use Slack Workflow Builder
2. Add ButterStack webhook step
3. Configure triggers:
   • Message reactions
   • Form submissions
   • Scheduled times

Analytics Integration

Track Slack interaction metrics:

• Message delivery rates
• Interaction frequencies
• Response times
• Most used commands

Troubleshooting

curl -X POST -H 'Content-type: application/json' \
  --data '{"text":"Test from ButterStack"}' \
  YOUR_WEBHOOK_URL

Best Practices

Integration Examples

Python Webhook Example

import requests
import json

def send_butterstack_notification(webhook_url, message):
    payload = {
        "text": "ButterStack Notification",
        "attachments": [{
            "color": "#5D5DFF",
            "title": message['title'],
            "text": message['description'],
            "fields": [
                {"title": "Status", "value": message['status'], "short": True},
                {"title": "Time", "value": message['timestamp'], "short": True}
            ],
            "footer": "ButterStack",
            "footer_icon": "https://app.butterstack.com/icon.png"
        }]
    }
    
    response = requests.post(
        webhook_url,
        data=json.dumps(payload),
        headers={'Content-Type': 'application/json'}
    )
    
    return response.status_code == 200

Copy Code

Related

• Discord Integration - Multi-channel notifications for gaming communities
• Troubleshooting - Common issues and solutions