> ## Documentation Index
> Fetch the complete documentation index at: https://docs.overcut.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Slack from self-hosted Overcut

> Connect Slack to a self-hosted Overcut deployment by creating your own Slack app.

Use this path when you run **Overcut on your own infrastructure**. A Slack app
has a single, fixed set
of URLs - its OAuth redirect, event delivery, and slash-command endpoints are
registered on the app itself - and the managed Overcut Cloud Slack app points
at Overcut Cloud. Your deployment therefore uses a Slack app that **you create
and own**, pointing at your own domain. All tokens and events stay between your
Slack workspace and your deployment; nothing goes through Overcut Cloud.

<Note>
  On **Overcut Cloud**, use the managed Overcut Slack app instead - see
  [Connect to Slack](/docs/integrations/slack). No app creation or environment
  configuration is needed there.
</Note>

## Prerequisites

* Permission to **create apps** in your Slack workspace (and, if your workspace
  requires it, admin approval to install them)
* A running self-hosted Overcut deployment with a public HTTPS domain
  (`https://<your-overcut-domain>`) and a **browser-trusted TLS certificate**
* **Inbound reachability from Slack**: Slack's servers must be able to reach
  `https://<your-overcut-domain>/hooks/...` over port 443
* The ability to set environment variables on the deployment and restart it

<Warning>
  Slack verifies your event endpoint with a live HTTPS request and delivers all
  events from Slack's cloud. A deployment behind a firewall that blocks inbound
  internet traffic, or one serving a self-signed certificate, **cannot
  complete Slack setup**. This is a Slack platform requirement, not an Overcut
  limitation.
</Warning>

## How it works

Your Slack app is the identity Overcut uses in Slack:

1. **OAuth connection** - connecting a Slack workspace in Overcut runs the
   OAuth flow against *your* app; the granted bot token is stored by your
   deployment and used to read and post messages.
2. **Events and commands** - Slack delivers channel messages, mentions, and
   slash commands to your deployment, signed with your app's **signing
   secret**, which Overcut verifies on every request.

## Step 1: Create the Slack app

<Steps>
  <Step title="Create the app from a manifest">
    Go to [api.slack.com/apps](https://api.slack.com/apps), click **Create New
    App -> From a manifest**, pick the Slack workspace, and paste the manifest
    below - replacing `<your-overcut-domain>` (three occurrences) with your
    deployment's domain:

    ```yaml theme={"dark"}
    display_information:
      name: Overcut
      description: Run Overcut workflows from Slack via mentions and slash commands.
      background_color: "#191919"
    features:
      bot_user:
        display_name: Overcut
        always_online: true
      slash_commands:
        - command: /overcut
          url: https://<your-overcut-domain>/hooks/slack/slash-command
          description: Trigger an Overcut workflow.
          usage_hint: "<command> [args]"
          should_escape: false
    oauth_config:
      redirect_urls:
        - https://<your-overcut-domain>/slack-auth-app/callback
      scopes:
        bot:
          - commands
          - app_mentions:read
          - channels:read
          - groups:read
          - channels:join
          - channels:history
          - groups:history
          - team:read
          - chat:write
          - reactions:write
    settings:
      event_subscriptions:
        request_url: https://<your-overcut-domain>/hooks/slack/events
        bot_events:
          - app_mention
          - message.channels
          - message.groups
      org_deploy_enabled: false
      socket_mode_enabled: false
      token_rotation_enabled: false
    ```

    Review the summary and click **Create**. Slack may warn that the event
    request URL is not yet verified - that is expected; you verify it in Step 2
    after the deployment knows the signing secret.
  </Step>

  <Step title="Collect the credentials">
    On the app's **Basic Information** page, under **App Credentials**, collect:

    * **App ID**
    * **Client ID**
    * **Client Secret**
    * **Signing Secret**
  </Step>
</Steps>

## Step 2: Configure the deployment

Set these environment variables on your deployment:

| Variable                    | Value                                                   |
| --------------------------- | ------------------------------------------------------- |
| `SLACK_INTEGRATION_ENABLED` | `true`                                                  |
| `SLACK_APP_ID`              | The **App ID**                                          |
| `SLACK_CLIENT_ID`           | The **Client ID**                                       |
| `SLACK_CLIENT_SECRET`       | The **Client Secret**                                   |
| `SLACK_SIGNING_SECRET`      | The **Signing Secret**                                  |
| `SLACK_REDIRECT_URI`        | `https://<your-overcut-domain>/slack-auth-app/callback` |

The redirect URI must be **byte-identical** to the redirect URL registered on
the Slack app (Step 1), otherwise the OAuth step fails with a
`redirect_uri` mismatch.

### Apply the configuration

Restart the deployment so the new environment variables take effect.

### Verify the event endpoint

Back in the Slack app settings, open **Event Subscriptions**. If the request
URL shows as unverified, click **Retry**. Slack sends a challenge to
`https://<your-overcut-domain>/hooks/slack/events`; with the deployment running
and the signing secret configured, it turns **Verified**.

## Step 3: Connect in Overcut

<Steps>
  <Step title="Open workspace Integrations">
    From the workspace sidebar (no project selected), go to **Integrations**.
  </Step>

  <Step title="Connect Slack">
    In the providers list, find **Slack** and click connect. You are redirected
    to Slack to authorize **your** app for the Slack workspace.
  </Step>

  <Step title="Approve the OAuth scopes">
    Approve the requested scopes. After approval you return to Overcut and the
    Slack workspace appears in the connected providers list.
  </Step>
</Steps>

From here, setup continues exactly as on Overcut Cloud - register channels in
a project, choose routing modes, and trigger workflows: see
[Connect to Slack](/docs/integrations/slack#register-channels-in-a-project).

## Troubleshooting

* **Slack tile missing or disabled in Overcut**: `SLACK_INTEGRATION_ENABLED` is
  not `true`, or the deployment was not restarted after setting it.
* **Event request URL verification fails**: Slack cannot reach
  `https://<your-overcut-domain>/hooks/slack/events` (check DNS, that port 443
  is open to the internet, and that the TLS certificate is browser-trusted -
  a self-signed certificate fails here), or `SLACK_SIGNING_SECRET` is not set
  on the deployment.
* **OAuth step fails with `redirect_uri` mismatch**: `SLACK_REDIRECT_URI` does
  not exactly match a redirect URL registered on the Slack app.
* **Events deliver but signature validation fails (401 in the deployment
  logs)**: the app's **Signing Secret** and the deployed `SLACK_SIGNING_SECRET`
  do not match - re-copy it from **Basic Information** and re-apply.
* **`/overcut` slash command returns an error in Slack**: the slash-command URL
  on the app does not point at
  `https://<your-overcut-domain>/hooks/slack/slash-command`, or the deployment
  is unreachable from Slack.
* **Messages in a channel do not trigger anything**: the bot is not in the
  channel, or the channel is not registered in the project - see
  [Register channels in a project](/docs/integrations/slack#register-channels-in-a-project).

For what you can do once connected (channels, routing modes, triggering
workflows, interactive sessions), see the
[Slack overview](/docs/integrations/slack).