Slack Integration

Connect a Slack workspace so DriftWise can post scheduled-scan failure notifications to channels you choose. Installation uses Slack's OAuth flow — DriftWise never sees your workspace password, and the bot token is stored encrypted at rest. For endpoint shapes, see the webhooks tag of the API reference (Slack install / status / uninstall live there alongside CI webhook configs).

Plan requirement

Slack integration is available on Team and Enterprise plans. Free-tier orgs receive 402 Payment Required when attempting to install. See Plans & Billing.

What it does

• Posts notifications when a scheduled scan fails, and again when a schedule is auto-disabled after repeated consecutive failures.
• Supports routing different schedules to different channels via each schedule's notify_slack_channel field.
• One active installation per org. Reinstalling the same workspace updates the existing record in place. Installing a different workspace makes the newer install the active one — status, delivery, and uninstall all target the most recent installation.

Not currently delivered over Slack: ad-hoc (non-scheduled) scan results, scan-success messages, drift-change summaries. These events exist in the product but don't flow through the notification dispatcher.

Installation

Via the UI

1. Open the Settings tab and find the Slack Integration card.
2. Click Add to Slack — the browser navigates to Slack's consent screen.
3. Pick the workspace, then approve the requested scopes (chat:write, incoming-webhook).
4. Slack redirects back to Settings with the integration marked Connected to your workspace name.

Slack will ask you to select a default channel as part of the incoming-webhook step. This is a Slack UX requirement — DriftWise does not actually post to that channel. Channels for actual notifications are picked per schedule via notify_slack_channel.

Only owner and admin role members can initiate or remove a Slack installation.

Via the API

The install endpoint returns a Slack authorization URL; the frontend redirects the browser to it. The OAuth state is HMAC-signed with the server's encryption key and bound to (org_id, user_id) so the callback can verify the state wasn't forged or replayed across tenants.

After the user approves on Slack, Slack redirects to the callback endpoint (outside the /api/v2 auth middleware by design), which verifies the signed state, re-checks org membership, re-checks plan eligibility, exchanges the authorization code for a bot token, and completes the installation.

The callback is rate-limited per source IP to block amplification via repeated outbound Slack API calls.

Inviting the bot to channels

After installation, invite the DriftWise bot to each channel you want notifications in:

/invite @driftwise

The bot uses the chat:write scope, which requires the bot to be a member of the channel it posts to. Once the bot is in a channel, reference the channel in your scheduled scan configuration by setting notify_slack_channel. Different schedules can post to different channels.

Checking status

The status endpoint returns installed=true with team_id, team_name, scopes, and created_at when the org has a valid bot token. installed=false with no metadata means no installation. A third shape — installed=false, available=false — means the DriftWise deployment itself has no Slack app configured (the integration can't be used at all), so the frontend should hide the integration tile.

Uninstall

Uninstall revokes the bot token against Slack's API (best-effort) and deletes the installation record from DriftWise. Owner/admin only. Revoke failures are logged but don't fail the endpoint — the local delete is the authoritative state.

Audit events

All install/uninstall actions write to the audit log:

Action	Recorded when
slack.installed	OAuth callback completes successfully
slack.uninstalled	Installation record is deleted

Both events record the Slack team_id and team_name. The bot token is never logged.

Security notes

• Bot tokens are encrypted at rest with the server's encryption key and only decrypted in-memory for posting.
• OAuth state is HMAC-signed and bound to (org_id, user_id) — prevents cross-org and cross-user CSRF.
• Org membership is re-verified inside the OAuth callback; if the user was removed between initiate and approve, the installation is rejected with 403.
• Plan eligibility is re-checked in the callback — a downgrade between initiate and approve causes the installation to fail closed.
• The callback endpoint is rate-limited per source IP to block amplification via repeated outbound Slack API calls.

Endpoint reference

Slack install, status, uninstall, and the OAuth callback are documented under the webhooks tag of the API reference. The callback itself is a browser redirect endpoint outside /api/v2 auth — it's called by Slack, not by API clients.