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

# Slack

> Route Tallwatch alerts to a Slack channel with an incoming webhook URL.

Tallwatch posts a structured incident card to Slack through an [incoming webhook](https://api.slack.com/messaging/webhooks). Setup takes about two minutes and needs admin access to the workspace.

Send alerts to a dedicated `#incidents` or `#alerts` channel, not a busy general channel where they'll scroll away.

## 1. Create the webhook in Slack

<Steps>
  <Step title="Create a Slack app">
    Go to [api.slack.com/apps](https://api.slack.com/apps), click **Create New App**, then **From scratch**. Name it something recognizable like `Tallwatch alerts` and pick the workspace.
  </Step>

  <Step title="Enable incoming webhooks">
    Under **Features**, open **Incoming Webhooks** and toggle **Activate Incoming Webhooks** on.
  </Step>

  <Step title="Add the webhook to a channel">
    Click **Add New Webhook to Workspace**, choose the channel that should receive alerts, then **Allow**.
  </Step>

  <Step title="Copy the URL">
    Slack returns a URL like `https://hooks.slack.com/services/T0XXXXX/B0XXXXX/AbCdEf...`. Copy it.
  </Step>
</Steps>

<Warning>
  Treat the webhook URL like a password. Anyone who has it can post to your channel as the app. If it leaks, regenerate it from the same Slack page.
</Warning>

## 2. Add the channel in Tallwatch

<Steps>
  <Step title="Open the channels page">
    Go to **Settings → Alerts → Channels** and click **Add channel**.
  </Step>

  <Step title="Pick Slack">
    Choose the Slack kind and name it for the audience, like `Engineering #incidents`.
  </Step>

  <Step title="Paste the URL and test">
    Paste the URL into **Incoming webhook URL**, click **Save**, then **Send test alert**. The message should arrive in Slack within a few seconds.
  </Step>
</Steps>

## 3. Route a monitor to it

Open a monitor's settings, pick an escalation policy that includes this Slack channel, and save. The next incident on that monitor fires to Slack.

No policy yet? The channel is picked up automatically by the workspace fallback, which fires every enabled channel for monitors without an explicit policy.

## What the alert looks like

One Slack message per incident event:

* The monitor name as a bold heading
* A colored sidebar, red for `incident.opened`, green for `incident.resolved`
* The failing regions
* The last error from the check
* A deep link back to the incident in the dashboard
* An **Acknowledge** button on a freshly opened incident, so you can pick it up from Slack without opening the dashboard

<Note>
  The in-Slack **Acknowledge** button needs the Tallwatch Slack app's signing
  secret configured on the backend; on a deployment without it, the button is
  omitted and the rest of the message is unchanged. Resolving still happens in
  the dashboard.
</Note>

## Troubleshooting

<AccordionGroup>
  <Accordion title="The test sent, but nothing arrived in Slack">
    Most often the channel was deleted or archived after you created the webhook. Slack silently drops messages to dead channels while the URL stays valid. Recreate the webhook against a live channel.

    Less often, the app was uninstalled. Reinstall it from the same Slack app page.
  </Accordion>

  <Accordion title="`invalid_payload` from Slack">
    The webhook URL is malformed or revoked. Regenerate it in the Slack app config and paste the new one into Tallwatch.
  </Accordion>

  <Accordion title="Some alerts arrive, some don't">
    Open the channel's dispatch history. Since every dispatch goes out immediately, a missing message is usually a `failed` row: Slack returned a non-2xx (deleted channel, revoked webhook), or during a burst its incoming-webhook limit of roughly one message per second rejected the flood. The failed row shows the exact response. If a noisy hour keeps hitting that limit, split those monitors across more than one Slack channel.
  </Accordion>

  <Accordion title="Alerts arrive but some fields look empty">
    Slack channels always send the canonical card, so there's nothing to configure beyond the URL. If a field is blank, the underlying incident genuinely lacks that value. Want a custom shape? Use a [Webhook channel](/alerts/webhook) and template the body.
  </Accordion>
</AccordionGroup>

## Reference

| Property        | Value                                                                   |
| --------------- | ----------------------------------------------------------------------- |
| Channel kind    | `slack`                                                                 |
| Required config | `webhook_url`                                                           |
| Delivery        | Immediate, no proactive rate limit; Slack enforces its own              |
| Retry           | Up to 3 inline attempts on 5xx, 429, network, or timeout, then `failed` |
| Outbound to     | `hooks.slack.com`                                                       |