> ## 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.

# Discord

> Route Tallwatch alerts to a Discord channel with a server webhook.

Tallwatch sends an embed-style incident message to Discord through a [channel webhook](https://support.discord.com/hc/en-us/articles/228383668-Intro-to-Webhooks). Setup takes about two minutes and needs **Manage Webhooks** on the server.

Point it at a dedicated channel like `#incidents` rather than your general chat.

## 1. Create the webhook in Discord

<Steps>
  <Step title="Open channel settings">
    Right-click the channel that should receive alerts and click **Edit Channel**.
  </Step>

  <Step title="Add a webhook">
    In the sidebar, click **Integrations → Webhooks → New Webhook**. Give it a name like `Tallwatch` and, optionally, an avatar. Alerts post under this identity.
  </Step>

  <Step title="Copy the URL">
    Click **Copy Webhook URL**. It looks like `https://discord.com/api/webhooks/9876543210/AbCdEf...`.
  </Step>
</Steps>

<Warning>
  The webhook URL is a credential. Anyone who has it can post as this identity in your server. If it leaks, click **Delete Webhook** in Discord and create a new one.
</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 Discord">
    Choose the Discord kind and name it for the audience, like `Discord #incidents`.
  </Step>

  <Step title="Paste the URL and test">
    Paste the URL into **Incoming webhook URL**, click **Save**, then **Send test alert**. The embed should appear in Discord almost immediately.
  </Step>
</Steps>

## What the alert looks like

One Discord embed per incident event:

* The monitor name as the embed title
* An embed color matched to the event, red for opened, green for resolved
* Inline fields for the event, monitor, URL, failing regions, when it opened, and the last error
* A link back to the incident in Tallwatch

## Troubleshooting

<AccordionGroup>
  <Accordion title="The test sent, but nothing arrived">
    The webhook was probably deleted on the Discord side. Discord drops messages to deleted webhooks without an error. Recreate it and update the URL in Tallwatch.

    It could also belong to a server you've lost access to. Re-check the URL under the channel's integration settings.
  </Accordion>

  <Accordion title="`webhook_invalid` in the dispatch history">
    The URL is malformed, expired, or revoked. Regenerate it in Discord and paste the new value into Tallwatch.
  </Accordion>

  <Accordion title="Alerts show a default bot name, not the one I picked">
    The webhook still works. Discord attaches the display name at creation time. To change it, edit the webhook in Discord; Tallwatch doesn't override the name on send.
  </Accordion>

  <Accordion title="Some alerts arrive much later than expected">
    Tallwatch sends every dispatch immediately, so the delay is on Discord's side. Discord rate-limits incoming webhooks, roughly 30 requests per minute per webhook, and returns `429` with a `retry-after` when a burst exceeds it. Check the dispatch history for `429` responses. If a noisy hour keeps hitting the limit, split those monitors across more than one Discord channel.
  </Accordion>
</AccordionGroup>

## Reference

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