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

# Mattermost

> Send DevHelm incident alerts to Mattermost channels using incoming webhooks

Connect DevHelm to Mattermost to receive incident notifications in your team channels. DevHelm posts to a Mattermost **incoming webhook**, so it works with both self-hosted and Mattermost Cloud instances.

## Setup

<Steps>
  <Step title="Create a Mattermost incoming webhook">
    1. In Mattermost, open **Main Menu** → **Integrations** → **Incoming Webhooks**
    2. Click **Add Incoming Webhook**
    3. Choose a display name (e.g., "DevHelm") and a default channel
    4. Click **Save** and copy the generated webhook URL (e.g., `https://mattermost.example.com/hooks/xxxxxxxxxxxx`)

    If you don't see **Incoming Webhooks**, an administrator must enable them in **System Console** → **Integrations** → **Integration Management**.
  </Step>

  <Step title="Create the alert channel in DevHelm">
    <CodeGroup>
      ```bash CLI theme={null}
      devhelm alert-channels create \
        --name "Mattermost Alerts" \
        --type mattermost \
        --config '{"channelType":"mattermost","webhookUrl":"https://mattermost.example.com/hooks/xxxxxxxxxxxx"}'
      ```

      ```yaml devhelm.yml theme={null}
      alertChannels:
        - name: Mattermost Alerts
          config:
            channelType: mattermost
            webhookUrl: ${MATTERMOST_WEBHOOK_URL}
            channel: incidents
            iconUrl: https://example.com/devhelm-icon.png
      ```
    </CodeGroup>
  </Step>

  <Step title="Test the channel">
    ```bash theme={null}
    devhelm alert-channels test <channel-id>
    ```
  </Step>
</Steps>

## Configuration

| Field        | Description                                                              | Required |
| ------------ | ------------------------------------------------------------------------ | -------- |
| `webhookUrl` | Mattermost incoming webhook URL                                          | Yes      |
| `channel`    | Override the webhook's default channel (e.g. `incidents` or `@username`) | No       |
| `iconUrl`    | Publicly accessible URL for a custom bot icon                            | No       |

### Channel and icon overrides

`channel` and `iconUrl` only take effect if your Mattermost server permits webhook overrides. Enable **System Console** → **Integrations** → **Integration Management** → **Enable integrations to override usernames** and **override profile picture icons**. The `iconUrl` must be reachable from your Mattermost server — relative paths or internal-only URLs are ignored.

## Troubleshooting

<AccordionGroup>
  <Accordion title="Webhook disabled or returns HTTP 403">
    Incoming webhooks can be turned off per-server. Confirm an administrator has enabled **System Console** → **Integrations** → **Integration Management** → **Enable Incoming Webhooks**, and that the webhook itself hasn't been deleted under **Integrations** → **Incoming Webhooks**.
  </Accordion>

  <Accordion title="Channel override has no effect">
    The webhook posts to its configured default channel unless the server allows overrides. Enable **Enable integrations to override usernames and icons** in the System Console, then re-run `devhelm alert-channels test <channel-id>`.
  </Accordion>

  <Accordion title="Self-hosted server with a self-signed certificate">
    DevHelm requires a valid TLS certificate for the webhook host. Install a certificate from a trusted CA (e.g. Let's Encrypt) on your Mattermost instance — self-signed certificates are rejected during delivery.
  </Accordion>
</AccordionGroup>