Skip to main content
Version: 0.0.1

POST /slack/events

The main webhook endpoint that receives and processes Slack events from the Slack Events API. This endpoint handles all incoming Slack events with comprehensive signature verification, event parsing, and queue publishing.

Endpoint Information​

Basic Details​

  • Method: POST
  • Path: /slack/events
  • Content-Type: application/json
  • Authentication: Slack signature verification (HMAC-SHA256)

Request Format​

Headers​

HeaderRequiredDescription
X-Slack-SignatureYesHMAC-SHA256 signature of the request
X-Slack-Request-TimestampYesUnix timestamp of the request
Content-TypeYesMust be application/json

Request Body​

The request body contains a JSON payload that varies depending on the event type:

Event Callback Structure​

{
  "token": "verification_token_deprecated",
  "team_id": "T1234567890",
  "api_app_id": "A1234567890",
  "event": {
    "type": "app_mention",
    "user": "U9876543210",
    "text": "<@U1234567890> hello there!",
    "ts": "1234567890.123456",
    "channel": "C1234567890",
    "event_ts": "1234567890.123456"
  },
  "type": "event_callback",
  "event_id": "Ev9876543210",
  "event_time": 1234567890,
  "authorizations": [
    {
      "enterprise_id": "E1234567890",
      "team_id": "T1234567890",
      "user_id": "U1234567890",
      "is_bot": true,
      "is_enterprise_install": false
    }
  ],
  "is_ext_shared_channel": false
}

URL Verification Challenge Structure​

{
  "token": "verification_token_deprecated",
  "challenge": "challenge_string",
  "type": "url_verification"
}

Response Formats​

Successful Event Processing​

{
  "status": "ok"
}

HTTP Status: 200 OK

URL Verification Challenge Response​

{
  "challenge": "challenge_string"
}

HTTP Status: 200 OK

Authentication Error​

{
  "detail": "Invalid request signature"
}

HTTP Status: 401 Unauthorized

Malformed Request Error​

{
  "detail": "Error description"
}

HTTP Status: 400 Bad Request

Event Processing Flow​

Supported Event Types​

Message Events​

App Mention Event​

{
  "type": "event_callback",
  "event": {
    "type": "app_mention",
    "user": "U9876543210",
    "text": "<@U1234567890> Can you help with this task?",
    "ts": "1234567890.123456",
    "channel": "C1234567890",
    "event_ts": "1234567890.123456",
    "thread_ts": "1234567889.654321"
  }
}

Message Event​

{
  "type": "event_callback",
  "event": {
    "type": "message",
    "user": "U9876543210",
    "text": "Hello everyone!",
    "ts": "1234567890.123456",
    "channel": "C1234567890",
    "event_ts": "1234567890.123456",
    "channel_type": "channel"
  }
}

Reaction Events​

Reaction Added Event​

{
  "type": "event_callback",
  "event": {
    "type": "reaction_added",
    "user": "U9876543210",
    "reaction": "thumbsup",
    "item": {
      "type": "message",
      "channel": "C1234567890",
      "ts": "1234567890.123456"
    },
    "event_ts": "1234567891.234567"
  }
}

Reaction Removed Event​

{
  "type": "event_callback",
  "event": {
    "type": "reaction_removed",
    "user": "U9876543210",
    "reaction": "thumbsup",
    "item": {
      "type": "message",
      "channel": "C1234567890",
      "ts": "1234567890.123456"
    },
    "event_ts": "1234567891.234567"
  }
}

Channel Events​

Member Joined Channel​

{
  "type": "event_callback",
  "event": {
    "type": "member_joined_channel",
    "user": "U9876543210",
    "channel": "C1234567890",
    "channel_type": "channel",
    "team": "T1234567890",
    "event_ts": "1234567890.123456",
    "inviter": "U1111111111"
  }
}

Error Handling​

Signature Verification Failure​

Cause: Invalid or missing Slack signature headers Response: 401 Unauthorized Details: The request signature could not be verified against the configured signing secret

JSON Parsing Error​

Cause: Malformed JSON in request body Response: 400 Bad Request Details: The request body could not be parsed as valid JSON

Event Processing Error​

Cause: Error during event processing or queue publishing Response: 200 OK (to prevent Slack retries) Details: Error logged but 200 returned to acknowledge receipt

Security Considerations​

Signature Verification​

The endpoint implements Slack's signature verification using HMAC-SHA256:

  1. Concatenation: Create a string by concatenating the version, timestamp, and request body
  2. HMAC Calculation: Calculate HMAC-SHA256 using the signing secret
  3. Comparison: Compare the calculated signature with the provided signature header
# Pseudo-code for signature verification
basestring = f"v0:{timestamp}:{body}"
expected_signature = f"v0={hmac.new(signing_secret, basestring, hashlib.sha256).hexdigest()}"
is_valid = hmac.compare_digest(expected_signature, slack_signature)

Request Validation​

  • Timestamp Check: Requests older than 5 minutes are rejected
  • Content-Type Validation: Only application/json requests are accepted
  • Payload Size Limits: Large payloads are rejected to prevent DoS attacks

Performance Characteristics​

Throughput​

  • High Concurrency: ASGI-based async processing
  • Low Latency: Minimal processing overhead per request
  • Queue Integration: Non-blocking event publishing

Resource Usage​

  • Memory Efficient: Streaming JSON parsing
  • CPU Optimized: Efficient signature verification
  • Network Optimized: Minimal response payloads

Development Testing​

Using ngrok for Local Testing​

  1. Start the webhook server locally:

    python -m slack_mcp.webhook --host 127.0.0.1 --port 3000

  2. Expose local server with ngrok:

    ngrok http 3000

  3. Configure Slack app with ngrok URL:

    https://abc123.ngrok.io/slack/events

Event Simulation​

For testing purposes, you can simulate Slack events:

curl -X POST http://localhost:3000/slack/events \
  -H "Content-Type: application/json" \
  -H "X-Slack-Signature: v0=signature" \
  -H "X-Slack-Request-Timestamp: $(date +%s)" \
  -d '{
    "type": "url_verification",
    "challenge": "test_challenge",
    "token": "deprecated_token"
  }'

Production Deployment​

Environment Variables​

# Required
SLACK_SIGNING_SECRET=your_signing_secret_here
SLACK_BOT_TOKEN=xoxb-your-bot-token

# Optional
SLACK_EVENTS_TOPIC=custom_topic_name

Docker Deployment​

FROM python:3.11-slim

WORKDIR /app
COPY requirements.txt .
RUN pip install -r requirements.txt

COPY . .

EXPOSE 3000
CMD ["python", "-m", "slack_mcp.webhook", "--host", "0.0.0.0", "--port", "3000"]

Health Check Endpoint​

While not implemented in the current version, you can add a health check:

@app.get("/health")
async def health_check():
    return {"status": "healthy", "timestamp": time.time()}

Monitoring and Logging​

Log Messages​

The endpoint logs important events:

[INFO] Handling URL verification challenge
[INFO] Received Slack event: app_mention
[INFO] Published event of type 'app_mention' to queue topic 'slack_events'
[WARNING] Invalid Slack request signature
[ERROR] Error publishing event to queue: ConnectionError

Metrics to Monitor​

  • Request Rate: Number of events per second
  • Success Rate: Percentage of successfully processed events
  • Error Rate: Percentage of failed signature verifications
  • Queue Publish Rate: Events successfully published to queue
  • Response Time: Average time to process and respond to events

Integration Examples​

Custom Event Handler​

from slack_mcp.webhook.server import create_slack_app

app = create_slack_app()

# Add custom middleware or event handlers
@app.middleware("http")
async def custom_logging(request, call_next):
    # Custom logging logic
    response = await call_next(request)
    return response

Queue Consumer Example​

import asyncio
from slack_mcp.backends.loader import load_backend

async def consume_events():
    backend = load_backend()
    
    async for event in backend.consume("slack_events"):
        event_type = event.get("event", {}).get("type")
        print(f"Processing event: {event_type}")
        # Custom event processing logic here