Skip to main content

Source: ocean/docs/slack-setup-walkthrough.md | ✏️ Edit on GitHub

Slack Setup Step-by-Step Walkthrough

Follow these steps in order to set up Slack notifications for Ocean.

Part 1: Create Your Slack App (5 minutes)​

Step 1: Go to Slack API​

  1. Open your browser and go to: https://api.slack.com/apps
  2. Make sure you're logged into your Slack workspace
  3. Click the green "Create New App" button

Step 2: Choose App Creation Method​

  1. Select "From scratch" (not from manifest)
  2. Fill in:
    • App Name: Ocean Alerts (or whatever you prefer)
    • Pick a workspace: Select your workspace from dropdown
  3. Click "Create App"

Step 3: You'll See Your App's Basic Information​

  • You should now be on the "Basic Information" page
  • Keep this tab open, we'll come back to it

Part 2: Set Up Incoming Webhooks (5 minutes)​

Step 1: Enable Incoming Webhooks​

  1. In the left sidebar, click "Incoming Webhooks"
  2. Toggle the switch at the top to ON (it will turn green)
  3. You'll see new options appear below

Step 2: Create Your First Webhook​

  1. Scroll down and click "Add New Webhook to Workspace"
  2. A new window will open asking where to post messages
  3. Select or create a channel called #alerts-critical
    • If it doesn't exist, type #alerts-critical to create it
  4. Click "Allow"

Step 3: Copy Your First Webhook URL​

  1. You'll be redirected back to the webhooks page

  2. You'll see your new webhook with a URL like:

    https://hooks.slack.com/services/T00000000/B00000000/XXXXXXXXXXXXXXXXXXXX

  3. Click "Copy" next to this URL

  4. Save it somewhere safe (we'll need it soon)

Step 4: Create Additional Webhooks​

Repeat Step 2-3 for these channels:

  • #alerts-errors - For application errors
  • #alerts-performance - For slow queries, performance issues
  • #alerts-analytics - For user events, signups, etc.

You should now have 4 webhook URLs saved.

Part 3: Create Slack Channels (2 minutes)​

In your Slack workspace, create these channels if they don't exist:

  1. In Slack, click the "+" next to "Channels"
  2. Click "Create a channel"
  3. Create these channels:
    • #alerts-critical - For urgent issues
    • #alerts-errors - For errors that need investigation
    • #alerts-performance - For performance issues
    • #alerts-analytics - For user activity
    • #alerts-security - For security events (optional)

Part 4: Store Webhook URLs Locally (3 minutes)​

Step 1: Create Environment File​

  1. In your Ocean project, create a file called .env.local if it doesn't exist

  2. Add your webhook URLs:

    # Slack Webhooks (for local testing)
    SLACK_WEBHOOK_CRITICAL=https://hooks.slack.com/services/YOUR/CRITICAL/WEBHOOK
    SLACK_WEBHOOK_ERRORS=https://hooks.slack.com/services/YOUR/ERRORS/WEBHOOK
    SLACK_WEBHOOK_PERFORMANCE=https://hooks.slack.com/services/YOUR/PERFORMANCE/WEBHOOK
    SLACK_WEBHOOK_ANALYTICS=https://hooks.slack.com/services/YOUR/ANALYTICS/WEBHOOK

  3. Replace the URLs with your actual webhook URLs from Part 2

Step 2: Test a Webhook​

Let's make sure it works. Run this in your terminal:

curl -X POST -H 'Content-Type: application/json' \
  -d '{"text":"🎉 Test message from Ocean setup!"}' \
  YOUR_CRITICAL_WEBHOOK_URL

Replace YOUR_CRITICAL_WEBHOOK_URL with your actual webhook URL.

You should see the message appear in #alerts-critical in Slack!

Part 5: Add Webhooks to Supabase (5 minutes)​

Step 1: Open Terminal in Your Project​

cd /Users/t/Developer/ocean

Step 2: Set Production Secrets​

Run these commands one by one, replacing with your actual webhook URLs:

supabase secrets set SLACK_WEBHOOK_CRITICAL="https://hooks.slack.com/services/YOUR/CRITICAL/WEBHOOK"
supabase secrets set SLACK_WEBHOOK_ERRORS="https://hooks.slack.com/services/YOUR/ERRORS/WEBHOOK"
supabase secrets set SLACK_WEBHOOK_PERFORMANCE="https://hooks.slack.com/services/YOUR/PERFORMANCE/WEBHOOK"
supabase secrets set SLACK_WEBHOOK_ANALYTICS="https://hooks.slack.com/services/YOUR/ANALYTICS/WEBHOOK"

Step 3: Deploy the Slack Alert Function​

supabase functions deploy send-slack-alert

You should see:

✓ Function deployed successfully

Part 6: Test Your Integration (3 minutes)​

Step 1: Test from Your App​

Add this temporary code to test (you can put it in any component):

import { sendSlackAlert } from '@/lib/slack-alerts'

// Add this to a button click or useEffect
const testSlack = async () => {
  const result = await sendSlackAlert({
    type: 'test',
    level: 'critical',
    message: '🧪 Test alert from Ocean - Setup complete!',
    details: {
      user: 'Setup Test',
      timestamp: new Date().toISOString(),
    },
  })

  console.log('Slack test result:', result)
}

Step 2: Check Slack​

You should see the test message in #alerts-critical

Part 7: Connect Sentry to Slack (5 minutes)​

Step 1: Log into Sentry​

  1. Go to your Sentry dashboard
  2. Click Settings (bottom left) → Integrations

Step 2: Install Slack Integration​

  1. Search for "Slack" in the integrations list
  2. Click "Install" (or "Configure" if already installed)
  3. Click "Add Workspace"
  4. You'll be redirected to Slack to authorize
  5. Click "Allow"

Step 3: Create Your First Alert Rule​

  1. Go to Alerts → Create Alert Rule
  2. Choose "Issue Alert"
  3. Configure:
    • Alert name: "Critical Production Errors"
    • Environment: Production
    • When: An event is seen
    • If: ALL of the following match:
      • Level is Error or Fatal
      • Environment equals production
    • Then: Send a Slack notification to #alerts-critical
  4. Click "Save Rule"

Step 4: Test Sentry Integration​

Add this to your app to test:

Sentry.captureMessage('Test Sentry-Slack integration', {
  level: 'error',
  tags: { test: true },
})

Part 8: Connect PostHog to Slack (5 minutes)​

Step 1: Log into PostHog​

  1. Go to your PostHog dashboard
  2. Click Apps in the sidebar

Step 2: Install Slack App​

  1. Search for "Slack"
  2. Click "Install"
  3. Configure:
    • Webhook URL: Use your analytics webhook URL
    • Click "Save"

Step 3: Create a User Signup Action​

  1. Go to Data Management → Actions
  2. Click "New Action"
  3. Configure:
    • Name: "New User Signup"
    • Match event: Select "Match event name"
    • Event name: user_signed_up
  4. Click "Save"
  5. In the action settings, add:
    • Post to webhook: Select your Slack webhook
    • Message: 🎉 New user signed up: {person.email}

Part 9: Test Everything Together (5 minutes)​

Test 1: Database Monitoring (pg_net)​

-- Run this in Supabase SQL editor to trigger an alert
INSERT INTO monitoring.pg_net_health (
  queue_size, response_size, status
) VALUES (
  15000, 60000, 'critical'
);

Test 2: Application Error​

// Add to your app temporarily
try {
  throw new Error('Test critical error for Slack')
} catch (error) {
  Sentry.captureException(error)
}

Test 3: Analytics Event​

// Trigger a test signup event
posthog.capture('user_signed_up', {
  email: 'test@example.com',
  plan: 'test',
})

Part 10: Clean Up and Next Steps​

Remove Test Code​

Remove any test code you added to your app

Set Channel Settings​

For each alert channel in Slack:

  1. Click the channel name → Settings → Edit
  2. Set topic: "Automated alerts - Do not post here manually"
  3. Pin a message with links to:
    • This setup guide
    • Sentry dashboard
    • PostHog dashboard
    • Supabase dashboard

Configure More Alerts​

Now that basic setup is complete, you can:

  1. Add more Sentry alert rules
  2. Create more PostHog actions
  3. Set up custom alerts using the sendSlackAlert function

Troubleshooting​

"Invalid webhook URL"​

  • Make sure the URL starts with https://hooks.slack.com/services/
  • Check for extra spaces or quotes around the URL

"No messages in Slack"​

  1. Check Edge Function logs:

    supabase functions logs send-slack-alert

  2. Verify secrets are set:

    supabase secrets list

"Sentry not sending to Slack"​

  1. Go to Sentry → Settings → Integrations → Slack
  2. Click "Test Configuration"
  3. Make sure your workspace is connected

Quick Reference Card​

Save this for easy access:

// Send critical alert
import { sendCriticalAlert } from '@/lib/slack-alerts'
await sendCriticalAlert('Payment Failed', 'Stripe error', {
  error_code: 'card_declined',
})

// Send performance alert
import { sendPerformanceAlert } from '@/lib/slack-alerts'
await sendPerformanceAlert('Slow query detected', {
  metric: 'query_time',
  value: 5000,
  threshold: 1000,
})

// Send custom alert
import { sendSlackAlert } from '@/lib/slack-alerts'
await sendSlackAlert({
  type: 'custom_event',
  level: 'info',
  message: 'Something happened',
  channel: 'analytics',
})

You're Done! 🎉​

Your Slack integration is now complete. You should be receiving:

  • 🚨 Critical alerts for major issues
  • ❌ Error notifications from Sentry
  • 📊 Analytics events from PostHog
  • 🐌 Performance alerts for slow queries
  • 🗄️ Database monitoring alerts (pg_net)