How Slackbots Work

You don’t need to read this guide to create a Slackbot. The Blink CLI does it all for you. This page explains the internals for those who want deeper insight.

Overview

Building a Slackbot typically involves navigating complex OAuth flows, managing webhook configurations, handling request verification, and maintaining separate development and production environments. Blink abstracts away these pain points, handling the heavy lifting automatically. Most of this work happens in the background with Blink. You can start building your bot immediately without worrying about webhook signatures, URL verification challenges, or tunnel configuration. However, if you want to understand what’s happening behind the scenes or need to troubleshoot something, this guide explains how Blink agents run in Slack, from development through production deployment.

How Blink Communicates with Slack

Before diving into setup, it’s helpful to understand how Blink agents communicate with Slack.

Webhook Architecture

Slack sends events (messages, mentions, reactions) to your agent via HTTP POST requests called webhooks. Here’s the flow:

User sends message in Slack
    ↓
Slack creates webhook POST request
    ↓
POST https://{your-webhook-uuid}.blink.host
    ↓
Blink receives and routes request
    ↓
Your agent processes the event
    ↓
Agent responds via Slack API

Request Verification

Every webhook request from Slack includes a cryptographic signature to verify authenticity:

Signature Header: x-slack-signature contains an HMAC-SHA256 hash
Timestamp Header: x-slack-request-timestamp prevents replay attacks
Signing Secret: Your app’s secret key used to verify signatures

Blink’s Slack SDK automatically handles verification - you don’t need to implement it yourself.

The Webhook Tunnel

During development, Blink provides a devhook - a reverse tunnel that routes webhooks from Slack to your local machine:

Development:
Slack → https://{uuid}.blink.host → Your localhost:3000

Production:
Slack → https://{uuid}.blink.host → Blink Cloud

The same URL works for both environments, making the transition from development to production easy.

During your first blink deploy you will be given the option to automatically migrate your devhook to the production webhook. Most users choose this option as managing separate development and production Slack apps is usually unnecessary.

Setting Up Your Slack App

The blink init command automates the entire Slack app creation process.

Step 1: Run the Setup Command

From your agent project directory:

blink init

After choosing Slackbot, the CLI will prompt you for your Slack app name:

What should your Slack app be called?
my-awesome-bot

This name appears in Slack when users interact with your bot, and can be changed later.

Step 2: Behind the Scenes - Devhook Creation

The CLI automatically:

Generates a unique tunnel ID (UUID)
Saves it to .blink/devhook.txt
Creates your webhook URL: https://{uuid}.blink.host

This URL forwards webhooks to your local machine during development.

The .blink/devhook.txt file is automatically added to .gitignore. Don’t commit this to version control.

Step 3: Slack App Manifest Generation

Blink creates a complete Slack app manifest with preconfigured: OAuth Scopes:

app_mentions:read - Detect @mentions
chat:write - Send messages
channels:history - Read channel messages
im:history, im:read, im:write - Handle DMs
users:read - Get user information
reactions:write, reactions:read - Add/read emoji reactions
files:read - Access uploaded files
assistant:write - Use Slack AI features (optional)

Event Subscriptions:

app_mention - When bot is @mentioned
message.channels - Channel messages
message.im - Direct messages
reaction_added, reaction_removed - Emoji reactions

Webhook Configuration:

All events route to your devhook URL
Includes interactivity for buttons and modals

Step 4: Create the Slack App

The CLI opens your browser to:

https://api.slack.com/apps?new_app=1&manifest_json={...}

In the Slack UI:

Choose workspace

Select which workspace to install the app

Review manifest

Slack shows the preconfigured app settings. This is where you can alter app descriptions and names.

Create app

Click “Create” - Slack provisions your app

Install to workspace

Click “Install to Workspace” and authorize permissions

Step 5: Provide Credentials

Return to your terminal. The CLI prompts for three pieces of information:

App ID

From the Basic Information page in Slack:

After creating the app, paste the App ID:
A01234567AB

Signing Secret

From the same Basic Information page:

Paste your Signing Secret:
•••••••••••••••••••••••••

The signing secret verifies that webhook requests actually come from Slack.

Bot Token

From the OAuth & Permissions page (after installing):

Paste your Bot Token:
•••••••••••••••••••••••••••••••

The CLI validates the token against Slack’s API before accepting it.

Step 6: Webhook Verification

The CLI starts a webhook listener and waits for connectivity:

✓ Webhook listener started
✓ Webhook challenge received

Try sending a DM to the bot - it's "my-awesome-bot" in the search bar.

Behind the scenes:

Listener connects to Blink’s devhook service via WebSocket
URL verification challenge - Slack sends a test request, CLI responds automatically
Signature verification - All incoming requests are verified
Test DM - You send a message, confirming end-to-end connectivity

If signature verification fails, the CLI prompts you to re-enter the signing secret.

Step 7: Success

Once the test DM arrives:

✓ DM received!
✓ Credentials saved to .env.local

Congrats, your app is now installed and ready to use!
Run `blink dev` to use your agent.

Your .env.local now contains:

SLACK_BOT_TOKEN=xoxb-your-token-here
SLACK_SIGNING_SECRET=your-signing-secret-here

Developing Your Slackbot

Starting the Development Server

blink dev

This command:

Loads environment variables from .env.local
Starts HTTP server on localhost:3000
Establishes devhook tunnel connection
Enables hot-reload for code changes

You’ll see:

blink■ dev

⚙ Send webhooks from anywhere: https://abc123.blink.host
🔄 Hot reload enabled
✓ Agent running on http://localhost:3000

Testing Your Bot

Open Slack and find your bot in the search bar
Send a DM or @mention it in a channel
View logs in your terminal showing request handling
Make code changes directly or via Edit Mode - they hot-reload automatically

Remember, to chat with your undeployed local agent via Slack, your terminal must be in blink dev and toggled to Run Mode.

Slack Message Formatting

Slack uses different formatting than standard Markdown:

Standard Markdown	Slack Format
`bold`	`bold`
`italic`	`_italic_`
`~~strikethrough~~`	`~strikethrough~`
`[text](url)`	`<url\|text>`
`@username`	`<@U123456>` (user ID)

The Slack SDK handles conversions automatically, but be aware when formatting messages.

Deploying to Production

Once your bot works locally, deploy it to Blink Cloud. After deploying, you can chat with your Slackbot without needing to be in blink dev. To deploy:

blink deploy

Environment Variable Migration

On first deployment, Blink prompts to copy environment variables:

Environment Variables
  Missing 2 vars in .env.production:
    SLACK_BOT_TOKEN, SLACK_SIGNING_SECRET

Copy missing vars from .env.local to .env.production? (Y/n)

Choose Yes to:

Copy credentials to .env.production file
Deploy them as encrypted secrets to Blink Cloud

Your .env files are automatically added to .gitignore.

Webhook Tunnel Migration

This is the key step that keeps your Slack integration working:

Webhook Tunnel
  Current: https://abc123.blink.host → local dev
  After: https://abc123.blink.host → production
  Migrating will keep your webhooks working in production

Migrate tunnel to production? (Y/n)

What tunnel migration does:

Preserves your webhook URL - No changes needed in your Slack manifest
Updates routing - Blink Cloud now handles requests instead of localhost
Resets local devhook - Generates new UUID for future dev work

If you choose Yes:

✅ Production immediately works with existing Slack app
✅ No webhook URL updates needed
⚠️ Local dev needs reconfiguration (see below)

If you choose No:

⚠️ You must manually update Slack’s webhook URL
✅ Local dev continues working unchanged

Recommended: Choose Yes for first deployment, unless you prefer to maintain separate Development and Production Slack apps.

After Deployment

✓ Deployed. All new chats will use this version.
https://blink.so/my-org/my-bot/deployments/1

Note: To continue developing locally with webhooks, you'll need to
reconfigure external services. Run `blink setup slack-app` to create
a new Slack app for development.

Your bot is now live! Test it in your Slack workspace.

Continuing Local Development After Migration

After migrating the webhook tunnel to production, you have two options for local development:

Option 1: Create a Separate Dev Slack App (Recommended)

Run blink setup slack-app again to:

Create a new Slack app dedicated to development
Generate a fresh devhook tunnel
Keep dev and prod environments isolated

Best practice: Name your dev app clearly (e.g., “My Bot [DEV]”) to distinguish it from production.

Option 2: Update Existing Slack App Webhook

Temporarily update your production Slack app’s webhook URL:

Run blink dev to get your new devhook URL
Go to Slack App Settings → Event Subscriptions
Update Request URL to the new devhook URL
Remember to revert before testing production changes

Option 2 means production webhooks won’t work while you’re developing. Use Option 1 for safer development.

Troubleshooting

Webhook Not Receiving Events

Check:

Run blink dev and verify the devhook URL is shown
In Slack app settings, verify Event Subscriptions → Request URL matches your devhook
Check that the URL shows a green “Verified” checkmark
Look for “Invalid signature” errors in terminal (wrong signing secret)

Fix:

# Regenerate credentials
blink setup slack-app

Invalid Signing Secret Error

The signing secret doesn’t match. This happens if:

You copied the wrong secret from Slack
You regenerated the secret in Slack but didn’t update .env.local

Fix:

Go to Slack app Basic Information page
Copy the current Signing Secret

Update .env.local:

SLACK_SIGNING_SECRET=your-correct-secret-here

Restart blink dev

Bot Not Responding to DMs

Check:

Bot user is online (should show as “Active”)
Your agent listens to message events (not just app_mention)
Event handler checks for is_im channel type
No errors in terminal logs

Example fix:

app.event("message", async ({ event }) => {
  // Ignore bot messages and threaded replies
  if (event.subtype || event.bot_id || event.thread_ts) return;

  // Check if DM
  const channelInfo = await app.client.conversations.info({
    channel: event.channel,
  });

  if (channelInfo.channel?.is_im) {
    // Handle DM
  }
});

Bot Not Responding to @Mentions

Check: 1. app_mentions:read scope is enabled 2. Event subscription includes app_mention 3. Handler is registered: app.event("app_mention", ...)

Production Webhook Not Working After Deployment

If you migrated the tunnel:

Webhook should work automatically
Check deployment succeeded (not “Failed” status)
Verify in Blink Cloud logs that requests are arriving

If you didn’t migrate:

Update Slack app webhook URL to your production URL
Find it in deployment output or Blink Cloud dashboard

Environment Variables Not Loading

Development:

Check .env.local exists and has correct syntax
No quotes needed around values: TOKEN=abc123 (not TOKEN="abc123")
Restart blink dev after editing

Production:

Verify .env.production was created before deploying
Check Blink Cloud dashboard → Agent → Settings → Environment Variables
Redeploy if variables were added after last deployment

Get Started

Blink Essentials

Agent Use Cases

Overview

How Blink Communicates with Slack

Webhook Architecture

Request Verification

The Webhook Tunnel

Setting Up Your Slack App

Step 1: Run the Setup Command

Step 2: Behind the Scenes - Devhook Creation

Step 3: Slack App Manifest Generation

Step 4: Create the Slack App

Step 5: Provide Credentials

App ID

Signing Secret

Bot Token

Step 6: Webhook Verification

Step 7: Success

Developing Your Slackbot

Starting the Development Server

Testing Your Bot

Slack Message Formatting

Deploying to Production

Environment Variable Migration

Webhook Tunnel Migration

After Deployment

Continuing Local Development After Migration

Option 1: Create a Separate Dev Slack App (Recommended)

Option 2: Update Existing Slack App Webhook

Troubleshooting

Get Started

Blink Essentials

Agent Use Cases

​Overview

​How Blink Communicates with Slack

​Webhook Architecture

​Request Verification

​The Webhook Tunnel

​Setting Up Your Slack App

​Step 1: Run the Setup Command

​Step 2: Behind the Scenes - Devhook Creation

​Step 3: Slack App Manifest Generation

​Step 4: Create the Slack App

​Step 5: Provide Credentials

​App ID

​Signing Secret

​Bot Token

​Step 6: Webhook Verification

​Step 7: Success

​Developing Your Slackbot

​Starting the Development Server

​Testing Your Bot

​Slack Message Formatting

​Deploying to Production

​Environment Variable Migration

​Webhook Tunnel Migration

​After Deployment

​Continuing Local Development After Migration

​Option 1: Create a Separate Dev Slack App (Recommended)

​Option 2: Update Existing Slack App Webhook

​Troubleshooting

Overview

How Blink Communicates with Slack

Webhook Architecture

Request Verification

The Webhook Tunnel

Setting Up Your Slack App

Step 1: Run the Setup Command

Step 2: Behind the Scenes - Devhook Creation

Step 3: Slack App Manifest Generation

Step 4: Create the Slack App

Step 5: Provide Credentials

App ID

Signing Secret

Bot Token

Step 6: Webhook Verification

Step 7: Success

Developing Your Slackbot

Starting the Development Server

Testing Your Bot

Slack Message Formatting

Deploying to Production

Environment Variable Migration

Webhook Tunnel Migration

After Deployment

Continuing Local Development After Migration

Option 1: Create a Separate Dev Slack App (Recommended)

Option 2: Update Existing Slack App Webhook

Troubleshooting