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

# Set up the Slack app for your dedicated Ryvn hub

> Create the Slack app your dedicated Ryvn hub uses for notifications, hand the client credentials to Ryvn, and connect a channel.

Your dedicated Ryvn hub sends notifications through a Slack app that your organization owns. You create the app in
Slack, send the client credentials to Ryvn, then connect it from your hub and choose a channel for notifications.

<Info>
  You need permission to **create and install apps** in your Slack workspace and the **hub domain** Ryvn gave you
  (for example `acme.ryvn-abc12.ryvn.run`). If your workspace requires app approval, ask a workspace owner or app manager
  to approve the app. You also need permission to manage integrations in your Ryvn organization to connect it.
</Info>

<Steps>
  <Step title="Create the app">
    Open [Your Apps](https://api.slack.com/apps), click **Create New App**, and choose **From scratch**.

    | Field     | Value                                                 |
    | --------- | ----------------------------------------------------- |
    | App Name  | `Ryvn` (or any name you prefer)                       |
    | Workspace | the workspace where you want to receive notifications |

    Click **Create App**.
  </Step>

  <Step title="Enable incoming webhooks">
    Open **Incoming Webhooks** and turn **Activate Incoming Webhooks** on.

    Ryvn uses an incoming webhook to deliver notifications to the channel you select during connection. The hub saves
    that webhook automatically when you connect Slack in a later step.
  </Step>

  <Step title="Configure OAuth and permissions">
    Open **OAuth & Permissions**. Under **Redirect URLs**, click **Add New Redirect URL**, enter the following URL,
    replacing `<hub>` with your hub domain, and click **Save URLs**:

    ```text theme={null}
    https://api.<hub>/v1/integrations/slack/oauth/callback
    ```

    For example, a hub at `acme.ryvn-abc12.ryvn.run` uses
    `https://api.acme.ryvn-abc12.ryvn.run/v1/integrations/slack/oauth/callback`.

    <Warning>
      Check the hub domain before you save. It decides where Slack sends the authorization code. Only use the domain
      Ryvn gave you directly, never one from an unsolicited link.
    </Warning>

    Under **Scopes → Bot Token Scopes**, configure these four scopes. Enabling incoming webhooks adds
    `incoming-webhook` automatically; add the other three with **Add an OAuth Scope**.

    | Scope              | Permission                                                              |
    | ------------------ | ----------------------------------------------------------------------- |
    | `incoming-webhook` | Post messages to the channel selected during connection                 |
    | `chat:write`       | Send messages as the app                                                |
    | `channels:read`    | View basic information about public channels                            |
    | `groups:read`      | View basic information about private channels the app has been added to |

    These are the scopes the hub requests during installation. Leave **User Token Scopes** empty, and leave
    **token rotation** and **PKCE** disabled. Socket Mode, Event Subscriptions, Interactivity and Slash Commands are
    not needed for notifications.

    <Note>
      An app created for this workspace can stay undistributed. If it must be installed in another workspace, follow
      Slack's [distribution setup](https://docs.slack.dev/app-management/distribution/) under **Manage Distribution**
      before connecting it there.
    </Note>
  </Step>

  <Step title="Hand the credentials to Ryvn">
    Open **Basic Information → App Credentials**. Send the following to your Ryvn contact over the agreed secure
    channel, never in plain-text email or chat:

    | Field         | Where to find it                           |
    | ------------- | ------------------------------------------ |
    | Client ID     | **App Credentials → Client ID**            |
    | Client secret | **App Credentials → Client Secret → Show** |

    Ryvn configures your hub with these credentials, enables the Slack integration, and tells you when it is ready.
    The signing secret, verification token and bot token are not required for this handoff.
  </Step>

  <Step title="Connect Slack from your hub">
    Sign in at `https://<hub>`, select the Ryvn organization that should receive notifications, and open
    **Settings → Notifications**. Click **Connect Slack**.

    On Slack's authorization screen, confirm the workspace, select the notification channel, and click **Allow**.
    To select a private channel, you must already be a member of it. Slack's
    [incoming webhook guide](https://docs.slack.dev/messaging/sending-messages-using-incoming-webhooks/) describes
    the channel selection flow.

    Wait for **Slack connected successfully**, then return to your hub's **Notifications** page.

    <Note>
      Start the connection from the hub. Installing from Slack's **Install App** page or using **Add New Webhook**
      does not save a notification destination in your Ryvn organization. If you already installed the app that way,
      return to the hub and click **Connect Slack** to complete the connection.
    </Note>
  </Step>

  <Step title="Test delivery and choose notifications">
    On **Settings → Notifications**, click **Test** on the Slack destination. Confirm that
    **This is a test notification from Ryvn** arrives in the selected channel.

    Under **Subscriptions**, enable the notification types you want to receive. The hub currently supports one Slack
    destination per Ryvn organization. Contact Ryvn if you need to replace an existing connection or change its channel.
  </Step>
</Steps>

## Troubleshooting

| Symptom                                   | What to check                                                                                                                                   |
| ----------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- |
| Slack rejects the redirect URL            | Check that the saved URL matches your hub's API domain and the full callback path above, then click **Save URLs**.                              |
| Slack requires approval                   | Ask a workspace owner or app manager to approve the app and its requested scopes.                                                               |
| The hub reports that Slack is not enabled | Ask your Ryvn contact to confirm the client credentials are configured and the integration is enabled.                                          |
| The connection fails after authorization  | Start again from **Connect Slack** in the same browser. If it still fails, ask Ryvn to check the client credentials and callback configuration. |
| The test notification does not arrive     | Check the selected channel, confirm it is not archived, and ask Ryvn to check whether the webhook or installation has been revoked.             |

## Updating the app later

When a Ryvn release needs additional permissions, Ryvn tells you what to change and how to reauthorize the connection.
Coordinate client-secret rotation with your Ryvn contact so the hub uses the new secret before you reconnect Slack.