Skip to main content

Source: ocean/docs/slack-integration-quickstart.md | ✏️ Edit on GitHub

Slack Integration Quick Start Guide

This is a condensed guide to get Slack notifications working quickly with Ocean.

Step 1: Create Slack App (5 minutes)​

  1. Go to API.slack.com/apps
  2. Click "Create New App" → "From scratch"
  3. Name: "Ocean Alerts", select your workspace
  4. Go to "Incoming Webhooks" → Toggle ON
  5. Click "Add New Webhook to Workspace"
  6. Create these channels and add webhooks:
    • #alerts-critical
    • #alerts-errors
    • #alerts-performance
    • #alerts-analytics

Step 2: Add Webhook URLs to Environment​

Add to your .env.local (for local testing):

# Slack Webhooks
SLACK_WEBHOOK_CRITICAL=https://hooks.slack.com/services/YOUR/WEBHOOK/URL
SLACK_WEBHOOK_ERRORS=https://hooks.slack.com/services/YOUR/WEBHOOK/URL
SLACK_WEBHOOK_PERFORMANCE=https://hooks.slack.com/services/YOUR/WEBHOOK/URL
SLACK_WEBHOOK_ANALYTICS=https://hooks.slack.com/services/YOUR/WEBHOOK/URL

Add to Supabase Edge Function secrets:

supabase secrets set SLACK_WEBHOOK_CRITICAL=https://hooks.slack.com/services/YOUR/WEBHOOK/URL
supabase secrets set SLACK_WEBHOOK_ERRORS=https://hooks.slack.com/services/YOUR/WEBHOOK/URL
supabase secrets set SLACK_WEBHOOK_PERFORMANCE=https://hooks.slack.com/services/YOUR/WEBHOOK/URL
supabase secrets set SLACK_WEBHOOK_ANALYTICS=https://hooks.slack.com/services/YOUR/WEBHOOK/URL

Step 3: Deploy Slack Alert Function​

# Deploy the Edge Function
supabase functions deploy send-slack-alert

Step 4: Configure Sentry​

  1. Go to Sentry → Settings → Integrations
  2. Install Slack integration
  3. Create alert rules:

Critical pg_net Alert​

Name: 'pg_net Critical Backlog'
Conditions:
  - When: An event is seen
  - Filters:
      - message CONTAINS "pg_net backlog"
      - tags.pg_net_status = critical
Actions:
  - Send to Slack #alerts-critical

High Error Rate​

Name: 'High Error Rate'
Conditions:
  - When: Error rate > 5%
  - For: 10 minutes
Actions:
  - Send to Slack #alerts-errors

Step 5: Configure PostHog​

  1. Go to PostHog → Apps
  2. Install "Slack" app
  3. Configure webhook URL
  4. Create actions:

New User Signup​

{
  "event": "user_signed_up",
  "slack_channel": "#alerts-analytics",
  "message": "🎉 New user: {{person.email}}"
}

Step 6: Test Your Integration​

Test from your app​

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

// Test critical alert
await sendSlackAlert({
  type: 'test',
  level: 'critical',
  message: '🧪 Test critical alert - ignore',
  details: {
    test: true,
    timestamp: new Date().toISOString(),
  },
})

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

// Test PostHog integration
posthog.capture('test_slack_event', {
  test: true,
  channel: '#alerts-analytics',
})

Test pg_net monitoring​

-- Trigger a test pg_net alert
INSERT INTO monitoring.pg_net_health (
  queue_size, response_size, status
) VALUES (
  15000, 60000, 'critical'
);

Common Webhook Formats​

Error Alert​

{
  "text": "🚨 Critical Error",
  "attachments": [
    {
      "color": "danger",
      "title": "Database Connection Failed",
      "fields": [
        { "title": "Error", "value": "Connection timeout", "short": true },
        { "title": "Time", "value": "2024-01-20 15:30:00", "short": true }
      ]
    }
  ]
}

Performance Alert​

{
  "text": "⚠️ Performance Warning",
  "attachments": [
    {
      "color": "warning",
      "title": "Slow Query Detected",
      "fields": [
        { "title": "Query Time", "value": "5.2s", "short": true },
        { "title": "Table", "value": "organizations", "short": true }
      ]
    }
  ]
}

Troubleshooting​

"Invalid webhook URL"​

  • Check URL format: must start with https://hooks.slack.com/services/
  • Verify webhook is active in Slack app settings

"No messages appearing"​

  • Check Supabase Edge Function logs: supabase functions logs send-slack-alert
  • Verify environment variables are set
  • Test webhook directly: curl -X POST -d '{"text":"test"}' YOUR_WEBHOOK_URL

"Rate limited by Slack"​

  • Implement batching for similar alerts
  • Use the rate limiter in slack-alerts.ts
  • Consider using threads for related alerts

Next Steps​

  1. Set up alert aggregation - Prevent spam during incidents
  2. Create runbooks - Link alerts to fix procedures
  3. Add PagerDuty - For critical after-hours alerts
  4. Custom formatting - Enhance message appearance

Quick Reference​

Send alerts from your app​

import { sendCriticalAlert, sendPerformanceAlert } from '@/lib/slack-alerts'

// Critical alert
await sendCriticalAlert('Payment Failed', 'Stripe webhook error', {
  error: 'Invalid webhook signature',
  customer_id: 'cus_123',
})

// Performance alert
await sendPerformanceAlert('Slow API Response', {
  metric: 'api_response_time',
  value: 5200,
  threshold: 3000,
  endpoint: '/api/billing',
})

Alert levels​

  • critical → #alerts-critical (immediate action needed)
  • error → #alerts-errors (errors that need investigation)
  • warning → #alerts-performance (performance issues)
  • info → #alerts-analytics (metrics, user events)