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
/forgealways 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 asunknown, 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
-
Create the Slack app. In your Slack workspace, create a Forge Slack app. Configure interactivity URL
https://<primary-convex-site>/slack/interactions, slash-command URLhttps://<primary-convex-site>/slack/commands, events URLhttps://<primary-convex-site>/slack/events, and OAuth redirect URIhttps://<primary-convex-site>/oauth/slack/callback. The four URLs all live on the primary Convex deployment — no per-environment URLs. -
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). -
Set shared env vars on every deployment that participates in the relay:
FORGE_RELAY_HMAC_SECRET(one secret, identical on every deployment) andFORGE_DEPLOYMENT_ID(a unique slug per deployment:primary,staging,pr-1234, etc). -
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/botForge 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. -
Register target deployments on the primary. For every non-primary deployment that needs to receive relayed traffic, add a row to the primary’s
slackDeploymentRegistrytable:{ deploymentId: "staging", url: "https://forge-staging.convex.site", enabled: true }. Writing a registry row requiresplatform:manage.
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 onstaging, 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 (Slackmpim, 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.slackpreference 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 outcomeskipped_pref. - Scopes require a reconnect. DMs use the Slack
im:writeandmpim:writescopes. 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.
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 Slackauth.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 theslackSendAudit 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.
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 theslack.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.
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 withReference: <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 inunmappedIdentityAttempts 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 theFORGE_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:
connections:manage. data.status is healthy, degraded or down, and scopeDrift lists scope differences. Read the most recent outbound sends, which needs audit:read:
forge_call_operation:
forge_call_read_operation:

