Slack integration

Slack link previews are optional. When configured, a session URL pasted into Slack expands into a card showing the repo, summary, owner, and (for private sessions) a lock placeholder. This page is the admin setup walkthrough.

Where it lives

/admin/slack — a dedicated wizard, not the generic settings form. The Server Settings page surfaces a summary block at the top with a deep-link into the wizard, so you can find it whether you start at /admin/settings or /admin/slack directly.

The three steps

The wizard is three steps and about 90 seconds end-to-end.

1. Create a Slack app from a tenant-specific manifest

The wizard generates a pre-filled Slack app manifest scoped to your tenant — request URLs, event subscriptions, slash commands, scopes. It deep-links into Slack’s “Create app from manifest” flow. You pick your workspace and Slack creates the app.

The manifest’s request URLs point back at your tenant origin. Behind a reverse proxy this matters; see Reverse proxy considerations below.

After Slack creates the app you’ll land on its Basic Information page. Open OAuth & Permissions in the left sidebar and click “Install to <Workspace>” — the manifest declares the bot user and the links:read / links:write scopes, but Slack still requires you to confirm the install before issuing the bot token. Without this step the Bot User OAuth Token doesn’t exist yet and Step 2 has nothing to paste.

2. Paste tokens back

Once the app is installed, the wizard asks for two values:

• Signing Secret — on the Basic Information page under App Credentials. Used to verify HMAC-SHA256 signatures on inbound Slack requests.
• Bot User OAuth Token (xoxb-…) — on the OAuth & Permissions page, visible only after the install step above. Used to call chat.unfurl and auth.test.

The wizard validates the bot token by calling Slack’s auth.test immediately. If the call fails (wrong workspace, revoked token), you get a clear error and nothing is persisted.

Both values are stored encrypted at rest in the same server_settings table as other admin settings.

3. Live unfurl verification (optional)

The wizard offers to poll the slack_inbound_events ledger so you can paste a session URL in any Slack channel and watch the wizard confirm the link_shared event arrived. If it doesn’t arrive within ~30 seconds, the wizard points you at the most likely cause (event subscription not approved in Slack, signing secret mismatch, origin mismatch).

This step is optional. Skip it if you’re confident; come back later.

Reverse proxy considerations

The wizard needs to know the tenant’s public origin to fill into the manifest. Resolution priority:

1. Slack:PublicOrigin config (encrypted, set via the wizard or appsettings)
2. Caller hint (the wizard passes NavigationManager.BaseUri from the Razor page)
3. Request.Host from the inbound HTTP request

Behind a reverse proxy (Cloudflare, Nginx, anything that rewrites Host), set Slack:PublicOrigin explicitly. The resolver deliberately does not read the raw X-Forwarded-Host header — the project’s UseForwardedHeaders only enables XForwardedFor and XForwardedProto, so reading the host header would let a spoofed value poison the persisted manifest origin. Setting Slack:PublicOrigin to your real public URL avoids the trap entirely.

A drift warning appears in the Server Settings summary if Slack:ManifestOrigin (the origin baked into the manifest at creation time) no longer matches the currently resolved origin. Slack apps don’t break immediately when the origin changes, but link_shared events will start failing — re-run the wizard after a domain change.

What the integration uses Slack for

Read-only. Kapacitor calls chat.unfurl in response to link_shared events. No messages are posted, no channels are joined, no commands are run.

Private sessions show a lock placeholder card with the repo name and “Session is private”. Org-public and public sessions render the full card.

Disabling

Two ways:

• Clear Slack:BotToken (or Slack:SigningSecret) in the settings page. Once either secret is empty, the Slack event handler short-circuits inbound requests as 200 OK with no work.
• Uninstall the Slack app from your workspace via Slack’s app directory. The tenant continues to hold the tokens but Slack will stop sending events to them.

Related

• Server Settings — where the wizard lives and how reloads work.
• Visibility & sharing — what controls whether a session’s Slack preview is the full card or the lock placeholder.