Slack

The Slack channel lets a tenant install Orbit into their own Slack workspace as a Slack App. Operators connect the workspace through the OAuth v2 authorize → callback flow; inbound Events API messages, slash commands, and interactivity payloads are POSTed back to Orbit and verified with the App’s signing secret.

This is the tenant-facing Slack App — distinct from the internal ops-alert webhook (DEVOTEL_SLACK_OPS_WEBHOOK_URL), which only posts Orbit’s own operational alerts to a Devotel-internal channel.

Operator setup

Configure the Slack App credentials once per deployment, in Secret Manager (or .env for local dev). Every variable below is optional at boot; the Slack channel stays disabled until the credentials are set.

Variable	Required	Purpose
`DEVOTEL_SLACK_CLIENT_ID`	To enable install	Slack App OAuth v2 client id. Used to build the `https://slack.com/oauth/v2/authorize` URL.
`DEVOTEL_SLACK_CLIENT_SECRET`	To enable install	Slack App OAuth v2 client secret. Used (HTTP Basic, with the client id) to redeem the temporary code at `https://slack.com/api/oauth.v2.access`.
`DEVOTEL_SLACK_SIGNING_SECRET`	To accept inbound	HMAC-SHA256 key that verifies inbound Events / slash-command / interactivity requests. Fail-closed (see below).
`DEVOTEL_SLACK_BOT_SCOPES`	Optional	Comma-separated OAuth v2 bot scopes requested at install. Defaults to the baseline set baked into `packages/shared/src/env.ts`; override only if the App adds optional scopes (e.g. `assistant:write`).
`DEVOTEL_SLACK_DEFAULT_CHANNEL`	Optional	Legacy — not used by this OAuth app. Belongs to a separate, older internal Slack-forwarding path (override → this variable → `general`). It has no effect on the tenant-facing OAuth app documented here, which posts to the channel chosen when the workspace is connected. See Default post channel.

In your Slack App configuration (api.slack.com/apps), find the client id + secret under Basic Information → App Credentials, and the signing secret on the same screen. Set the Slack App’s Redirect URL to:

https://api.orbit.devotel.io/api/v1/integrations/slack/oauth/callback

Default bot scopes

If DEVOTEL_SLACK_BOT_SCOPES is unset, Orbit requests the following baseline scopes:

chat:write, chat:write.public, commands, app_mentions:read,
channels:history, channels:read, groups:history, groups:read,
im:history, im:write, users:read, users:read.email,
reactions:read, links:read, files:write

Default post channel

When the connected Slack App posts a tenant-side event (new conversation, campaign completed, SLA breach, voice-queue SLA warning) it resolves the destination channel in this order:

A channel explicitly named on the individual notification, when one is supplied.
The channel chosen when the workspace was connected.

There is no environment-variable or general fallback on this path. If no channel is configured — or the workspace has no active connection — the App drops the notification silently: it logs at debug level and never throws or fails the action behind it. This is deliberate: notification delivery is fail-open so that a Slack misconfiguration can never block the campaign send, conversation create, or SLA escalation that triggered it. Choose a notifications channel when connecting the workspace so these events have a place to land. The bot must be a member of the target channel, or hold the chat:write.public scope (included in the default scope set above) to post to a public channel it has not joined; otherwise Slack returns channel_not_found and the post fails.

DEVOTEL_SLACK_DEFAULT_CHANNEL and the general fallback belong to a separate, legacy internal Slack-forwarding path, not to this OAuth app. They have no effect on tenant notification delivery through the connected Slack App.

Install flow (OAuth v2)

From the dashboard, navigate to Channels → Slack and click Connect Workspace. This calls the authenticated start route, which mints an HMAC-signed state token and redirects the operator’s browser to Slack’s authorize screen.
GET /api/v1/integrations/slack/oauth/start
The operator approves the requested bot scopes in Slack.
Slack redirects the browser (a top-level navigation) back to the public callback route, which verifies the signed state, resolves the tenant from the verified payload, redeems the temporary code, and stores the workspace credentials in the tenant schema.
GET /api/v1/integrations/slack/oauth/callback

The callback is intentionally registered before Clerk auth (public scope) because browsers do not reliably carry the session cookie across Slack’s cross-site redirect. Trust is anchored on the HMAC-signed state round-trip, not on a session cookie.

Worked example — start the install (curl)

The start route requires an authenticated session (Clerk cookie) or a valid API key. A cold request with no session returns 401:

curl -sG "https://api.orbit.devotel.io/api/v1/integrations/slack/oauth/start" \
  -H "X-API-Key: dv_live_sk_your_key_here"

200 OK

{
  "data": {
    "authorize_url": "https://slack.com/oauth/v2/authorize?client_id=SLACK_CLIENT_ID&scope=chat%3Awrite%2Cchat%3Awrite.public%2Ccommands%2Capp_mentions%3Aread&redirect_uri=https%3A%2F%2Fapi.orbit.devotel.io%2Fapi%2Fv1%2Fintegrations%2Fslack%2Foauth%2Fcallback&state=eyJvcmdJZCI6Im9yZ18yNmF1MSIsInRzIjoxNzU2ODQ0MDAwLCJub25jZSI6ImFiMTIzIn0.9f8e4b2c1d3e…"
  },
  "meta": {
    "request_id": "req_c3f5d4e2a1b4",
    "timestamp": "2026-08-22T10:31:00.000Z"
  }
}

The authorize_url body field is the Slack authorize URL — the browser is redirected there on the dashboard click (this route returns JSON so the dashboard can surface a proper error rather than a bare redirect). The state query parameter has the form:

eyJvcmdJZCI6Im…   .   9f8e4b2c1d3e…
  base64url(JSON{orgId, ts, nonce})       HMAC-SHA256 hex

orgId is the tenant’s Orbit org; ts enforces a 10-minute TTL on the round-trip; nonce prevents replay. The callback rejects a tampered or expired state with 401 INVALID_STATE (see the errors table below). A continued install flow is purely browser-side: the operator clicks the authorize_url, approves in Slack, and Slack’s redirect hits GET /api/v1/integrations/slack/oauth/callback?code=…&state=…. There is no need to call /callback directly from your own code — it is part of the OAuth redirect.

Worked example — callback (browser round-trip)

After the operator approves:

GET /api/v1/integrations/slack/oauth/callback?code=1234.5.abc&state=eyJvcmdJZCI6Im…       .   9f8e4b2c1d3e…

200 OK (workspace stored):

{
  "data": {
    "ok": true,
    "team_id": "T012345",
    "team_name": "Acme Corp",
    "bot_user_id": "U06ABC123"
  },
  "meta": {
    "request_id": "req_a1b2c3d4",
    "timestamp": "2026-08-22T10:33:12.000Z"
  }
}

401 Unauthorized (state tampered or older than 10 min):

{
  "error": {
    "code": "INVALID_STATE",
    "message": "Slack OAuth state failed HMAC verification (or expired)",
    "status": 401
  },
  "meta": {
    "request_id": "req_a1b2c3d4",
    "timestamp": "2026-08-22T10:33:12.000Z"
  }
}

A 503 SLACK_NOT_CONFIGURED means DEVOTEL_SLACK_SIGNING_SECRET (or the client id/secret pair) is not set on the deployment — see the Common errors table.

Inbound request verification

Point your Slack App’s Event Subscriptions, Slash Commands, and Interactivity Request URLs at either of the equivalent inbound endpoints:

POST /api/v1/integrations/webhooks/slack    (canonical)
POST /api/v1/webhooks/slack/events          (Slack-convention alias)

Both mounts share one handler — the same signature gate, tenant resolution, and dispatch. Orbit verifies every inbound request per Slack’s verifying-requests-from-slack spec:

X-Slack-Signature: v0=<hex>
where  v0  = HMAC-SHA256(DEVOTEL_SLACK_SIGNING_SECRET, "v0:" + X-Slack-Request-Timestamp + ":" + rawBody)

The request timestamp (X-Slack-Request-Timestamp) must be within 5 minutes of now (Slack’s documented replay-protection window).

Worked example — Events API inbound (curl)

Slack’s Events API POSTs the raw JSON body to the Request URL. The X-Slack-Signature / X-Slack-Request-Timestamp headers authenticate the request as coming from Slack; the body is whatever the App subscribed to.

# Example of what Slack sends; shown so you can inspect the wire shape.
# Re-sign nothing yourself — Slack computes X-Slack-Signature + Timestamp.
TS=1723413120
BODY='{"type":"event_callback","team_id":"T012345","event_id":"Ev0Y2Z","event":{"type":"app_mention","user":"U7KLM9","channel":"C012345","text":"<@U06ABC123> hi","event_ts":"1723413120.30"}}'

curl -s -X POST "https://api.orbit.devotel.io/api/v1/integrations/webhooks/slack" \
  -H "Content-Type: application/json" \
  -H "X-Slack-Signature: v0=9f8e4b2c1d3e…" \
  -H "X-Slack-Request-Timestamp: ${TS}" \
  --data-binary "${BODY}"

v0 is HMAC-SHA256 of v0:${TS}:${BODY} keyed on the Slack App’s signing secret — Slack computes it per delivery. During development you can replay a captured delivery with curl only within the 5-minute window Slack’s own spec allows; after that, re-derive the signature or let Slack retry. 200 OK — a connected workspace, event persisted + dispatched:

{
  "data": {
    "received": true,
    "duplicate": false,
    "event_type": "app_mention"
  },
  "meta": {
    "request_id": "req_d4e5f6a7",
    "timestamp": "2026-08-22T10:40:12.000Z"
  }
}

The same endpoint returns 200 with duplicate: true when Slack retries a previously-acked event (Slack retries up to 3 times on non-200; Orbit deduplicates on event_id). 401 Unauthorized — forged or stale signature:

{
  "error": {
    "code": "INVALID_SIGNATURE",
    "message": "Could not verify the Slack webhook signature.",
    "status": 401
  },
  "meta": {
    "request_id": "req_d4e5f6a7",
    "timestamp": "2026-08-22T10:40:12.000Z"
  }
}

503 Service Unavailable — channel disabled because DEVOTEL_SLACK_SIGNING_SECRET is unset (fail-closed; never accept unsigned events):

{
  "error": {
    "code": "SLACK_NOT_CONFIGURED",
    "message": "Slack integration is not configured (DEVOTEL_SLACK_SIGNING_SECRET unset)",
    "status": 503
  },
  "meta": {
    "request_id": "req_d4e5f6a7",
    "timestamp": "2026-08-22T10:40:12.000Z"
  }
}

Node.js SDK (optional)

Slack is not on the SDK’s resource list — use the low-level request() escape hatch to mint an authorize URL or check the integration status.

import { Orbit } from '@devotel-orbit/node';

const orbit = new Orbit({ apiKey: 'dv_live_sk_your_key_here' });

// Mint the Slack authorize URL for the connected tenant.
const start = await orbit.request<{ data: { authorize_url: string } }>(
  'GET',
  '/api/v1/integrations/slack/oauth/start',
);

console.log(start.data.authorize_url);
// → https://slack.com/oauth/v2/authorize?client_id=…&state=…

The request() helper handles API-key attach, JSON serialisation, idempotency, 429/5xx retry, and OrbitApiError non-2xx handling — same as every SDK resource.

Fail-closed behaviour

The receiver fails closed — it will not accept inbound events it cannot authenticate:

`DEVOTEL_SLACK_SIGNING_SECRET`	Inbound request	Result
Set	Valid signature, fresh timestamp	`200` — processed
Set	Bad/missing signature, or timestamp older than 5 min	`401` — rejected
Unset	Any	`503` — channel disabled (never accept unsigned events)

So an operator must set the signing secret before enabling the Slack channel; otherwise inbound deliveries return 503 and Slack will disable the subscription after repeated non-200s.

Common errors

Symptom	Cause	Fix
Install returns `503` from `/start`	`DEVOTEL_SLACK_CLIENT_ID` / `DEVOTEL_SLACK_CLIENT_SECRET` unset	Set the App credentials in Secret Manager and redeploy.
Inbound events return `503`	`DEVOTEL_SLACK_SIGNING_SECRET` unset	Set the signing secret before enabling the channel.
Inbound events return `401`	Signing-secret mismatch or stale timestamp (clock skew > 5 min)	Re-copy the signing secret from Basic Information; verify host clock (NTP).
Slack disabled the subscription	Repeated non-200s on the Request URL	Fix the secret, then re-enable Event Subscriptions in the Slack App.

Getting Started

Channels

Channels (Voice)

AI Agents

Flows

Numbers & Verify

Concepts

Features

Billing

Webhooks

Security & SSO

Compliance

Legal

Changelog

Install Orbit into a Slack workspace via OAuth

Slack

Operator setup

Default bot scopes

Default post channel

Install flow (OAuth v2)

Worked example — start the install (curl)

Worked example — callback (browser round-trip)

Inbound request verification

Worked example — Events API inbound (curl)

Node.js SDK (optional)

Fail-closed behaviour

Common errors

​Slack

​Operator setup

​Default bot scopes

​Default post channel

​Install flow (OAuth v2)

​Worked example — start the install (curl)

​Worked example — callback (browser round-trip)

​Inbound request verification

​Worked example — Events API inbound (curl)

​Node.js SDK (optional)

​Fail-closed behaviour

​Common errors

Slack

Operator setup

Default bot scopes

Default post channel

Install flow (OAuth v2)

Worked example — start the install (curl)

Worked example — callback (browser round-trip)

Inbound request verification

Worked example — Events API inbound (curl)

Node.js SDK (optional)

Fail-closed behaviour

Common errors