​

Project Slack notifications (stacked on webhooks)

​

Goal

​

Non-goals (v2)

• In-app channel picker / changing channel without re-auth
• Bot token + chat.postMessage multi-channel routing
• Slack Marketplace listing / interactive Slack actions
• Renaming API/DB from webhooks → notifications (UI only for now)
• Org-level Slack install separate from per-project destinations

​

Product decisions

​

Data model

• provider text NOT NULL DEFAULT 'generic' CHECK (provider IN ('generic', 'slack'))
• display_name text NULL — e.g. #pipeline-alerts for Slack rows

• url — for Slack, the hooks.slack.com/... URL from OAuth
• secret — still generated; not used when posting to Slack (URL is the credential). List/create API must not expose Slack URLs; show display_name instead
• events[], enabled, delivery log / delivery_key behavior

​

OAuth + create flow

1. User selects events in Project Settings → Notifications.
2. Clicks Add to Slack.
3. Frontend calls GET /projects/{project_id}/webhooks/slack/authorize?events=... (requires project:update).
4. Backend returns Slack authorize URL with:
   • scope: incoming-webhook
   • signed, short-lived state binding project_id, events, user id, nonce
5. User picks workspace + channel on Slack → Allow.
6. Slack redirects to GET /api/integrations/slack/callback?code=&state= (or equivalent public callback route).
7. Backend verifies state, exchanges code, reads incoming_webhook.{url, channel, channel_id}.
8. Inserts project_webhooks row: provider=slack, url, display_name from channel, events from state.
9. Redirects browser to Project Settings → Notifications with success toast. On deny/error, redirect with failure toast.

​

UI

• Short description: notify on selected project events via Slack or HTTPS
• Event checkboxes (existing pipeline events)
• Primary: Add to Slack
• Secondary: URL field + Add HTTPS endpoint
• Destinations list:
  • Slack rows: Slack · #channel (+ events, enabled toggle, menu)
  • HTTPS rows: host/path truncation (existing behavior)
• No one-time HMAC secret dialog for Slack creates
• Test action: Slack-formatted ping for Slack rows; existing test for generic

​

Delivery

​

Edge cases

• User denies Slack → toast, no row
• App install blocked by workspace admin → surface Slack error + help
• Re-adding the same channel creates another row (no upsert by channel_id in v2)
• Change channel: delete destination + Add to Slack again
• Enabled-cap race: existing advisory lock covers Slack inserts that enable immediately

​

Testing

• Unit: OAuth state sign/verify; Block Kit builder; delivery branch (Slack vs generic)
• Callback handler with mocked Slack token exchange → creates provider=slack row with expected fields
• No live Slack workspace in CI

​

Implementation stack

main
 └── feat/project-pipeline-webhooks   #1345
      └── feat/project-slack-notifications   ← this work

1. Migration + provider field + API list/create shapes
2. Slack OAuth authorize + callback + row create
3. Delivery Block Kit branch + host allowlist
4. Frontend Notifications rename + Add to Slack button