Skip to main content
This page is for operators standing up Slack as an interaction surface for Forge. The end goal is: a single Slack app driving every Forge deployment, with approvals, slash commands, and Block Kit interactions routing to the right database.

How the Slack gateway works

A single Slack app drives every Forge deployment. Slash commands, button clicks, modal submissions and events all land at one deployment — the primary — which verifies Slack’s signature, works out which deployment owns the workflow, and relays the request there over a signed internal channel. Staging, preview and replica deployments never need their own Slack-facing URLs.
  • The routing host travels with the message. Every button Forge posts carries the identifier of the deployment that owns it, and every modal carries it in its metadata. Because Slack signs the whole payload, a tampered routing host fails Slack’s signature check.
  • Slack is answered first. The primary acknowledges Slack within Slack’s 3-second budget, then relays. The target deployment checks the relay signature, ignores duplicates, runs the handler, and updates the Slack message.
  • A relay is bound to its target. Each relay is signed for one specific deployment, so it cannot be replayed against another.
  • A failed relay tells the user. If the primary cannot reach the owning deployment, the person who clicked sees “Forge couldn’t reach the deployment that owns this workflow.”
  • Slash commands run on the primary. A slash command carries no workflow context, so /forge always runs against the primary deployment’s data.

Resolution on any surface

The same approval can be shown in Slack and in the Forge Console at once, and either can resolve it. Forge records every place it presented a prompt; when someone resolves it anywhere, it updates or withdraws every other presentation. The resolved message names the surface — “Resolved on Slack — 3 min ago” or “Resolved on Console” — and the approval record stores the same value. A Slack-side cleanup failure never undoes the resolution in Forge.

Delivery truth

Outbound Slack writes go through a durable outbox. Explicit Slack rate-limit and server errors can retry with recorded evidence. A timeout or lost connection after sending is recorded as unknown, not replayed, because Slack may have received the request. Files are stored as Forge files and attached only at send time.

Capability ownership and installation identity

Slack is a provider for Forge capabilities; it is not a parallel application layer. The provider can serve notifications, human interaction, chat syndication, publish, and org structure. Slack-specific ingress interprets and verifies Slack payloads, then hands typed requests to the owning capability. Only that capability’s consumer mutates Forge domain state. This keeps workflow decisions, chat state, governance, and worker identity vendor-neutral. Each installed workspace is identified by the pair (connectionId, slackTeamId). Runtime calls resolve the installation’s exact credentialId; credentials must target slack/bot and carry the same org-unit scope as the connection. Resolution fails closed when the installation is missing, ambiguous, inactive, unhealthy, revoked, expired, or scoped incorrectly. A token is never selected merely because it belongs to the same organization. The workspace install creates one Forge Credential targeting slack/bot, scoped to the org unit that owns the installation (for example, Gloo LLC), and links its ID to the workspace connection. That credential is the shared runtime credential for every Slack-backed capability: notifications, human interaction, chat syndication, publish, and org structure. Forge does not mint a separate credential per capability, and the providers do not read a parallel Slack token store or deployment environment fallback. The org scope is the authorization boundary; it does not restrict the credential to a single capability. The Forge Console workspace-connection view exposes this installation identity and health state so operators can diagnose routing without inspecting secrets. Ordinary outbound writes are placed in the durable delivery outbox. A visible unknown result means Slack may have received the request: verify Slack first, then reconcile it with an operator note rather than replaying automatically. The native-agent flag is per connection and disabled by default.

What you are setting up

One Slack app. One primary Convex deployment that owns the Slack-facing URLs. Zero or more target deployments (staging, preview environments, production replicas) that participate in the relay through HMAC-signed internal endpoints. Operators have two responsibilities on every environment: configure environment variables, and — for non-primary deployments — register a row on the primary’s deployment registry so the relay knows where to reach you.

Install — first-time setup

  1. Create the Slack app. In your Slack workspace, create a Forge Slack app. Configure interactivity URL https://<primary-convex-site>/slack/interactions, slash-command URL https://<primary-convex-site>/slack/commands, events URL https://<primary-convex-site>/slack/events, and OAuth redirect URI https://<primary-convex-site>/oauth/slack/callback. The four URLs all live on the primary Convex deployment — no per-environment URLs.
  2. Set primary-only env vars in the Convex dashboard for the primary deployment: SLACK_SIGNING_SECRET, SLACK_CLIENT_ID, SLACK_CLIENT_SECRET, SLACK_OAUTH_STATE_SECRET (generate a fresh secret — 32 bytes hex is fine), SLACK_OAUTH_REDIRECT_URI (must match the Slack app config exactly), CONSOLE_BASE_URL (the Forge Console origin).
  3. Set shared env vars on every deployment that participates in the relay: FORGE_RELAY_HMAC_SECRET (one secret, identical on every deployment) and FORGE_DEPLOYMENT_ID (a unique slug per deployment: primary, staging, pr-1234, etc).
  4. Install the app per Slack workspace. From the Forge Console, navigate to Platform → Capabilities → Providers → Slack, then click Connect another workspace. The browser redirects to Slack, the user authorizes the install, and Slack redirects back to the OAuth callback. The callback creates the org-scoped slack/bot Forge Credential, publishes the workspace connection only after that credential is linked successfully, and immediately schedules the workspace’s org-structure sync. A new install no longer waits for the daily 06:00 UTC sync.
  5. Register target deployments on the primary. For every non-primary deployment that needs to receive relayed traffic, add a row to the primary’s slackDeploymentRegistry table: { deploymentId: "staging", url: "https://forge-staging.convex.site", enabled: true }. Writing a registry row requires platform:manage.
Verify the install end-to-end. After install completes, use Verify workspace, then Send test DM to me, under Platform → Capabilities → Providers → Slack. Next, post a real test approval through Forge. The DM and approval should appear in Slack, the Approve / Reject buttons should resolve cleanly, and /observe should show the corresponding slack_gateway events in the unified timeline.

Slack app URLs

Configure these on the Slack app. All of them point at the primary deployment. Each route verifies Slack’s request signature with a 5-minute replay window and answers 401 on failure, or 500 if SLACK_SIGNING_SECRET is not set.

Environment variables

Set these in the deployment’s environment settings, not in .env files.

Multi-environment routing

Once primary and targets are wired, the routing decision is automatic and embedded in every Block Kit payload. When the workforce composes a Slack message from a workflow running on staging, every button’s action.value carries staging as field 0. When the user clicks the button, Slack POSTs to the primary, the primary extracts staging from the payload, looks up the registry row, signs an envelope with FORGE_RELAY_HMAC_SECRET, and POSTs it to https://forge-staging.convex.site/internal/slack-relay. Staging verifies the HMAC, dedupes on the idempotency key, runs the handler, and updates the Slack message via chat.update. The operator does not need to teach Slack about each environment. The routing host is metadata on every outbound presentation, and the registry on primary is the only mapping that needs to stay in sync.

Direct messages

Notifications and approvals can reach a specific person rather than a shared channel. When a notification or an approval is addressed to a worker, Forge resolves that worker’s linked Slack identity and delivers the message as a direct message — a 1:1 DM for a single recipient, or a group DM (Slack mpim, 2–8 recipients) when several workers are addressed at once. Delivery is worker-native: the addressing is by Forge worker, and the Slack user is resolved through the worker’s identity claim. If a worker has no linked Slack identity — or has turned DMs off — the platform falls back to the configured channel and @-mentions the intended recipients there, so a message is never silently dropped. Two operator-relevant controls:
  • Per-worker opt-out. Each worker can disable Slack DMs from the My Work settings. When a worker opts out, delivery to that worker cascades to the channel fallback. For a group DM, the all-or-nothing gate applies: if any addressed worker is unresolved or opted out, the whole audience cascades to the channel rather than delivering a partial DM.
  • Per-user Slack channel preference. Independently of the worker-level opt-out, a user who sets Slack off in their notification-channel preferences is dropped from DM audiences — the gate reads the same channels.slack preference the email fanout reads. The gate is fail-safe: a user with no linked account, no preference row, or an unresolvable identity is treated as opted in (delivery proceeds), so a preference lookup can never silently suppress a message. Each drop is recorded in the outbound delivery ledger with outcome skipped_pref.
  • Scopes require a reconnect. DMs use the Slack im:write and mpim:write scopes. A workspace connected before DM support was added will not have them. Reconnect the Slack app from Platform → Capabilities → Providers → Slack to grant the new scopes; until then, DM-addressed messages cascade to the channel fallback.
Confirm DM delivery. Platform → Capabilities → Providers → Slack includes Sync Slack users, Verify workspace, and Send test DM to me. Sync first if the operator is not mapped, verify the connection, then send the DM. Forge resolves your Slack identity claim for the exact installed workspace; a claim for another Slack workspace is never selected as a fallback. A failed conversations.open displays Slack’s error code and request ID for support escalation.

Credential verification and lifecycle

The Slack row under Platform → Vendors → Slack is intentionally labeled Slack OAuth managed. It represents the same Forge Credential created by the workspace install. Operators do not paste, edit, or rotate its token on the Vendor page; use Manage Slack workspaces to return to the Slack provider page. The row also exposes the shared credential system’s Verify now control. It resolves that exact credential and calls Slack auth.test; it does not create or consult a second Slack credential store. Verify workspace is the deeper installation check. It resolves the credential by the connection’s exact credentialId and org scope, calls Slack auth.test, and requires Slack to return both the stored workspace ID and stored bot user ID. A valid token for a different workspace or bot fails closed. The result updates the workspace lifecycle and health shown in the Console. Sync Slack users runs the canonical org_structure/slack capability for that exact workspace. The row shows the completion time plus matched and unmapped counts, and names the recovery action when the sync fails. The daily 06:00 UTC sync remains a repair backstop. Verify returns a status of healthy, degraded or down, and the workspace row’s health label changes to match: The following results come from Send test DM, not from Verify: Non-expiring Slack bot tokens have no refresh token and must not enter refresh-token rotation. The deployment initializer repairs only the historical, narrowly identified reinstall_required / refresh_token_missing state produced by the former selector bug; it does not reactivate other failed, expired, or revoked credentials.

Drift detection

A cron on the primary fans out /internal/whoami pings to every enabled registry row. The whoami response carries the target’s deploymentId, its current git SHA, and a structured slackTokenStatus (ok / missing / malformed). Three outcomes are recorded inline on the registry row: After three consecutive failures, the registry row’s enabled flag flips to false and the primary stops dispatching to that target. Re-enabling is an operator action — set enabled = true once you have confirmed the target is healthy and whoami returns ok. Auto-recovery is intentionally not wired; a flapping target should be silent until an operator vouches for it.

Outbound delivery ledger

Every outbound Slack send now leaves a row in the slackSendAudit ledger — the outbound mirror of the inbound relay audit. Before, a failed send was visible only as a console.error in the Convex logs; now each attempt records its surface, target channel, outcome, and (on success) the Slack message timestamp. The ledger never stores message content. Nine surfaces are instrumented: ops alerts, run-threaded posts, notification DMs, human-interaction prompts, agent publish (body + per-file upload), chat syndication, simple messages, and App Home publishes. Each row’s outcome is one of: A send that will deliver is recorded first, as an attempt row; if that row cannot be written, the send does not happen. The row is then updated with the outcome. A skipped send is recorded after the fact and never blocks anything, because nothing is delivered. Rows are rotated by the same slack gateway audit retention cron as the relay audit, on the SLACK_AUDIT_RETENTION_DAYS horizon (default 30 days).

Alert Slack sink

Observability alert rules (Observe → Alerts) can deliver to Slack. When creating a rule, choose the Slack sink and enter a Slack channel ID (Cxxxxxxx for a public/private channel or Gxxxxxxx for a group) — the bot must be a member of that channel. A firing rule posts the alert title and match summary to that channel; the delivery is recorded in the outbound ledger like any other send.
Channel ID, not name. The sink targets a raw Slack channel ID, not a #channel name. Copy it from Slack (channel → View channel details → the ID at the bottom). The console validates the C/G prefix format before saving.

App Home

Opening the Forge app’s Home tab in Slack shows the signed-in user their actionable work without leaving Slack:
  • Waiting for you — up to 10 open tasks that ask you, newest first: approvals, workflow steps, agent setup requests, and questions an agent asked you. Each is drawn from its form. When the form can be answered in Slack, Home shows its buttons (or a select, or a short reason dialog); otherwise it shows one Open in Forge link (an agent question opens in My Work). The buttons carry the same action encoding as the task’s prompt, so the same authorization gate applies: a click is governed identically whether it comes from a channel prompt, a DM, or Home. Platform review tasks (synthesis requests, held procedure drafts, judge admissions and curator recommendations) are not listed here or in /forge approvals; they are in My Work.
  • Running workflows — the workflows the user has triggered (console/API dispatches), with status and start time.
  • Run a workflow — opens the workflow picker modal, and a link into the Forge Console.
An unmapped Slack user (no linked Forge worker) sees a short “link your account” message instead. App Home requires the App Home tab and the app_home_opened event subscription to be enabled in the Slack app configuration — no new OAuth scope.

The /forge slash vocabulary

Beyond run <workflow> and the bare picker, the slash command understands three read-only sub-commands. All require a mapped Forge worker but not workflows:use:

Launching a workflow from Slack

/forge with no text opens a picker; /forge run <name> dispatches directly. Both compose from the workflow’s canonical input contract, so what Slack asks for matches what the Console asks for — parameters only. Typed widgets. A month parameter renders a generated rolling ±12-month select with the current month suggested; date renders Slack’s date picker (which can only emit YYYY-MM-DD, so a malformed date is unreachable); number and integer render a numeric input Slack validates before submit; a short enum renders as radio buttons and a longer one as a dropdown; a string[] with an enum renders as checkboxes. Dispatch validation performs no coercion, so each of these removes a class of rejection the operator would otherwise discover only after pressing Run. Pre-filled — for authorized users. Block Kit has no client-side evaluation, so the seed priority runs server-side when the modal is composed: the last completed production run → the parameter’s defaultExpr → its static default. The monthly close opens with last month already selected. Those seeds are prior-run data — argument values, and a bound asset’s filename — not contract metadata, so they are gated on a real workflows:use check even when the inbound authorization posture is temporarily set to warn. The posture governs whether an unauthorized action is blocked; it does not govern who sees data. A workspace member without workflows:use still gets the full contract from the picker, blank. If your operators report the modal opening empty, check their workflows:use grant before suspecting the seed logic. Derived and bound inputs are shown, not asked. Computed values appear as context lines under the form (acumaticaPeriods = ["052026"]), and a bound asset shows its current file and when it changed. Neither is editable from Slack — an asset is workflows:manage configuration and a launch surface must not override it. Large registries. Above 100 workflows the picker switches from a static dropdown (which Slack silently truncates at 100) to a type-ahead external_select. That requires an Options Load URL in the Slack app config pointed at https://<deployment>.convex.site/slack/options-load. Set it during install; without it the type-ahead returns an empty menu.

Zero-tap launch (feature-flagged, default OFF)

With the slack.zero-tap-launch feature flag enabled, /forge run <name> posts a confirm card instead of dispatching immediately, whenever every required parameter resolves: the parameter values, the derived expansion, the asset binding, a Console deep link, and [Launch] [Adjust…] [Cancel]. Launch dispatches exactly what the card displayed; Adjust opens the pre-filled modal; Cancel rewrites the card. A double-tap starts one run.
Release gate. The flag is seeded off as a reversible product rollout control. Slack authorization is independent: Slack inbound authorization always enforces, so a Slack user without the required permission is denied and the decision is audited. Before enabling zero-tap launch, review the 30-day grant audit on the Slack provider surface.

When Forge refuses

A refusal in Slack or email says what happened in a sentence. It never shows a code, an internal id, or a status. Examples are a Slack command run without the permission, an approval you can’t release, or a direct message from an account not linked to a Forge person. When Forge recorded a decision for the refusal, the reply ends with Reference: <id>.. Give that reference to an administrator, who can find the decision it names in the Trust Fabric decision log. The reply has no Console link, because the decisions page does not open a recorded denial for the person refused.

Where to look in the Forge Console

Four surfaces hold the operator-visible signal for the gateway. Observe → Events (/observe). Filter to the slack_gateway category to see relay decisions in the unified timeline. Each event carries the decision, outcome, host, action id, and payloadDigest. Use the digest to correlate a primary-side row with the target-side audit on the other end. Platform → Schedules (/platform/schedules). Three Slack-gateway crons run on the primary: slack gateway audit retention (deletes both the relay audit and the outbound slackSendAudit ledger rows older than SLACK_AUDIT_RETENTION_DAYS, default 30 days), slack gateway idempotency gc (evicts dedup rows past their 5-minute TTL), slack gateway drift detection (the whoami fan-out described above). Watch their last-run statuses here. Platform → Capabilities → Notifications (/platform/capabilities/notifications). The Recent Slack sends card renders the outbound delivery ledger described above — time, surface, event type, channel, and a color-coded outcome badge, with an error tooltip and a per-surface filter. This is the fastest way to answer “did that alert / approval / publish actually reach Slack, and if not, why.” Reading it requires the audit:read permission. Trust Fabric → Decisions (/trust-fabric/decisions). The append-only compliance view. Every approval that resolved through Slack carries actorIdentity.kind: "slack" and the payloadDigest that links to the primary’s audit row. Use this when the question is “who actually approved this, on what surface, and can I prove it.” Platform → Capabilities → Providers → Slack (/platform/capabilities/providers/slack). Workspace install management. It lists connected workspaces, scopes, install timestamps, linked credential health, Verify workspace, Send test DM to me, reconnect, and disconnect controls. The workspace list and its delivery-problem list read the workspaces homed at exactly the org unit the page names (workspaces homed at its descendants are not listed), then keep only those whose org unit is inside your scope closure: a platform-scope role grant keeps them all, and an org-unit grant keeps them only when the named unit is that unit or under it.

Common failure modes

The set below covers the recurring issues. For each, the symptom names what the operator sees, and the resolution names the env var or registry row to check first. Slack returns “your Slack account isn’t linked to a Forge worker yet.” An operator with no Forge worker tried to use the gateway. Resolution: invite the user as a worker on the relevant org unit. The unmapped attempt is recorded in unmappedIdentityAttempts for admin triage. A button click produces the ephemeral “Forge couldn’t reach the deployment that owns this workflow.” The primary couldn’t relay to the target. Check slackRelayAudit for the matching row — decision will be target_unknown (no registry row), secret_missing (FORGE_RELAY_HMAC_SECRET not configured), self_relay_refused (registry URL points at primary), or relayed with outcome=target_failed (network or HMAC issue on the target). OAuth install lands on the Console with ?error=<reason>. The install callback returns to the Slack provider page with a reason: Drift detection auto-disables a registry row. Three consecutive /internal/whoami failures. Inspect lastWhoAmIError for the category: timeout / dns_error / tls_error point at infrastructure; http_<status> means the target is up but the route isn’t mounted (verify the gateway code is deployed); shape_mismatch or wrong_deployment_id mean a stale or misconfigured target. Re-enable manually once healthy. Inbound rejection rate spikes. slackRelayAuditFallback shows a burst of bad_signature or replay_window_exceeded rows. The reject path is sampled 1-in-10 by default — actual rejection volume is 10× what you see in the audit. If this is an attack, raise SLACK_RELAY_REJECT_SAMPLE_RATE to 100 to further reduce database volume; the structured log lines still alert on volume even when sampled out. Audit rows label a relay legacy_fallback. A composer somewhere is still emitting pre-gateway button shapes (no host prefix). The legacy fallback routes to the primary, so behavior is correct, but the signal means a message composer still needs migrating; report it to the Forge team.

Do it over the API

These calls use the FORGE_BASE set up in the Raw HTTP tab of the quickstart. These operations refuse an External App token: send a Personal key or a platform API key as the bearer instead of the quickstart’s ACCESS_TOKEN, with scopes that include connections:manage and audit:read. The install, environment variables and registry rows are set up as described above; these calls verify a connected workspace and read the outbound delivery ledger. List an org unit’s connected workspaces:
Verify one workspace’s bot credential with Slack and record its health:
Both need connections:manage. data.status is healthy, degraded or down, and scopeDrift lists scope differences. Read the most recent outbound sends, which needs audit:read:
Over MCP, run the health check with forge_call_operation:
and list workspaces with forge_call_read_operation: