Slack PostHog Annotation Bot

A Slack bot that creates PostHog annotations when you @mention it in a thread.

How it works

1. Someone posts a message in Slack (e.g., "Deployed checkout v2.0")
2. Reply in thread and @mention the bot: @PostHog Bot release deployment
3. Bot creates an annotation in PostHog with the original message + your note
4. Bot replies with confirmation and link to the annotation

Setup

1. Create Slack App

1. Go to api.slack.com/apps → Create New App → From scratch
2. Name it (e.g., "PostHog Annotations") and select your workspace

OAuth & Permissions:

• Add Bot Token Scopes:
  • app_mentions:read - To receive @mentions
  • channels:history - To read parent messages in public channels
  • groups:history - To read parent messages in private channels
  • chat:write - To reply with confirmation
  • users:read - To get user names for attribution
• Install to Workspace and copy the Bot User OAuth Token (xoxb-...)

Event Subscriptions:

• Enable Events
• Subscribe to bot events:
  • app_mention
• Request URL: Set this after deploying (Step 4)

2. Get PostHog Credentials

1. Go to PostHog → Settings → Personal API Keys
2. Create a new key with annotation write scope
3. Note your Project ID from Project Settings

3. Configure Environment

cp .env.example .env
# Edit .env with your values

4. Deploy to AWS Lambda

Requires AWS SAM CLI.

# Build
sam build

# Deploy (will prompt for parameters on first run)
sam deploy --guided

After deployment, you'll get an endpoint URL like:

https://xxxxxxxxxx.execute-api.ap-south-1.amazonaws.com/Prod/slack/events

5. Configure Slack Event URL

1. Go back to your Slack App → Event Subscriptions
2. Set Request URL to your Lambda endpoint
3. Slack will verify the endpoint automatically

6. Invite Bot to Channel

Invite the bot to the channel(s) where you want to use it:

/invite @PostHog Annotations

Usage

Original message: "Just deployed the new payment flow to production"
  └── @PostHog Bot payment system release
      └── ✅ Annotation created in PostHog!

The annotation will include:

• The original message text
• Your custom note (if provided)
• Attribution (who posted the original message)

Commands

sam build                        # Build the application
sam deploy                       # Deploy to dev stage
sam deploy --config-env prod     # Deploy to production
sam logs -n SlackFunction --tail # Tail Lambda logs
sam delete                       # Remove the stack