Skip to main content
Version: 0.0.1

Webhook Server Modes

The webhook server supports two operational modes to accommodate different deployment scenarios and architectural requirements.

Mode Overview​

FeatureStandalone ModeIntegrated Mode
PurposeWebhook-only serverWebhook + MCP combined
Endpoints/slack/events/slack/events + MCP endpoints
Use CaseMicroservices, webhook-onlyFull Slack integration
MCP Tools❌ None✅ 6 Slack tools available
Port UsageSingle portSingle port (both services)
DeploymentLightweightFeature-complete

Standalone Mode​

The standalone server mode provides a dedicated webhook server focused solely on receiving and processing Slack events. This lightweight deployment option is ideal for microservices architectures and scenarios where you only need webhook functionality.

Endpoints​

  • Base URL: http://your-server:port
  • Primary Endpoint: POST /slack/events

Command Line Usage​

# Start standalone webhook server with defaults
python -m slack_mcp.webhook

# Explicit configuration
python -m slack_mcp.webhook \
  --host 0.0.0.0 \
  --port 3000 \
  --log-level INFO \
  --retry 3

CLI Arguments (Standalone Only)​

ArgumentTypeDefaultDescription
--hoststring"0.0.0.0"Server bind address
--portint3000Server port
--log-levelstring"INFO"Logging verbosity
--slack-tokenstringNoneOverride bot token
--env-filestring".env"Environment file path
--no-env-fileflagFalseDisable env file loading
--retryint3Network retry attempts
note

The --integrated, --mcp-transport, and --mcp-mount-path options are not available in standalone mode.

Integrated Mode​

The integrated server mode combines both MCP (Model Context Protocol) and webhook functionalities in a single FastAPI application. This unified deployment approach provides complete Slack integration capabilities.

Endpoints​

  • Base URL: http://your-server:port
  • MCP Endpoints: /mcp (SSE) or / (streamable-http)
  • Webhook Endpoint: POST /slack/events

Command Line Usage​

# Start integrated server with default SSE transport
python -m slack_mcp.webhook --integrated

# Explicit configuration
python -m slack_mcp.webhook \
  --integrated \
  --mcp-transport sse \
  --mcp-mount-path /mcp \
  --host 0.0.0.0 \
  --port 3000

CLI Arguments (Integrated Mode)​

ArgumentTypeDefaultDescription
--integratedflagFalseEnable integrated mode
--mcp-transportchoice"sse"MCP transport: sse or streamable-http
--mcp-mount-pathstring"/mcp"MCP mount path (SSE transport only)
--hoststring"0.0.0.0"Server bind address
--portint3000Server port
--log-levelstring"INFO"Logging verbosity
--slack-tokenstringNoneOverride bot token
--env-filestring".env"Environment file path
--no-env-fileflagFalseDisable env file loading
--retryint3Network retry attempts

MCP Transport Options​

# Server-Sent Events (default for integrated mode)
python -m slack_mcp.webhook \
  --integrated \
  --mcp-transport sse \
  --mcp-mount-path /api/mcp

# Endpoints created:
# GET  /api/mcp - MCP Server-Sent Events endpoint
# POST /api/mcp - MCP HTTP requests (optional)

Available MCP Tools​

The integrated server provides 6 MCP tools for Slack integration:

  1. post_slack_message - Send messages to channels
  2. read_slack_channels - List and read channel information
  3. reply_to_slack_thread - Reply to message threads
  4. add_slack_reaction - Add emoji reactions to messages
  5. read_slack_emojis - Get workspace emoji information
  6. read_slack_threads - Read message thread contents

Common Configuration​

Both modes share the same environment variables and webhook endpoint behavior.

Required Environment Variables​

export SLACK_SIGNING_SECRET="your_signing_secret_here"
export SLACK_BOT_TOKEN="xoxb-your-bot-token-here"

Optional Environment Variables​

# Webhook-specific configuration
export SLACK_EVENTS_TOPIC="slack_events_production"
export QUEUE_BACKEND_TYPE="redis"
export REDIS_URL="redis://localhost:6379/0"
export HOST="0.0.0.0"
export PORT="8080"
export LOG_LEVEL="INFO"

Webhook Endpoint Behavior​

Both modes handle the same webhook endpoint with identical behavior:

POST /slack/events​

Request Headers:

Content-Type: application/json
X-Slack-Signature: v0=<signature>
X-Slack-Request-Timestamp: <timestamp>

Response:

HTTP/1.1 200 OK
Content-Type: application/json

{"status": "ok"}

Response Codes​

StatusDescription
200 OKEvent processed successfully
400 Bad RequestInvalid request format or headers
401 UnauthorizedAuthentication failed
500 Internal Server ErrorServer processing error

Queue Backend Support​

Both modes support configurable queue backends for event processing:

export QUEUE_BACKEND_TYPE="redis"
export REDIS_URL="redis://localhost:6379/0"

Choosing the Right Mode​

Use Standalone Mode When:​

  • You only need webhook event processing
  • Building a microservices architecture
  • Deploying webhook handling separately from MCP functionality
  • Minimizing resource usage and dependencies

Use Integrated Mode When:​

  • You need both webhook events and MCP tool capabilities
  • Building a unified Slack integration service
  • Simplifying deployment with a single server process
  • Leveraging MCP tools for programmatic Slack interactions

For deployment and configuration details:

For architecture details: