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

# Alert Channels in YAML

> Define DevHelm alert channels in YAML — Slack, PagerDuty, Discord, email, and webhook configurations

The `alertChannels` section of `devhelm.yml` defines where incident notifications are sent. Each channel has a name and a `config` block whose `channelType` discriminator selects the integration.

## Common fields

| Field    | Type   | Required | Description                                                        |
| -------- | ------ | -------- | ------------------------------------------------------------------ |
| `name`   | string | Yes      | Unique channel name (used to reference from monitors and policies) |
| `config` | object | Yes      | Type-specific configuration. Must include `channelType`.           |

The schema is `.strict()` — any extra top-level keys (like a bare `type:`) are
rejected at validate / plan / deploy. Always nest the integration kind inside
`config.channelType`.

## Channel types

### Slack

```yaml theme={null}
alertChannels:
  - name: Slack Alerts
    config:
      channelType: slack
      webhookUrl: ${SLACK_WEBHOOK_URL}
      mentionText: "@channel"
```

| Config field  | Required | Description                                            |
| ------------- | -------- | ------------------------------------------------------ |
| `channelType` | Yes      | Always `slack`                                         |
| `webhookUrl`  | Yes      | Slack incoming webhook URL                             |
| `mentionText` | —        | Text to mention (e.g., `@channel`, `@here`, `<@U123>`) |

### PagerDuty

```yaml theme={null}
alertChannels:
  - name: PagerDuty On-Call
    config:
      channelType: pagerduty
      routingKey: ${PAGERDUTY_ROUTING_KEY}
      severityOverride: critical
```

| Config field       | Required | Description                         |
| ------------------ | -------- | ----------------------------------- |
| `channelType`      | Yes      | Always `pagerduty`                  |
| `routingKey`       | Yes      | PagerDuty Events API v2 routing key |
| `severityOverride` | —        | Override severity sent to PagerDuty |

### OpsGenie

```yaml theme={null}
alertChannels:
  - name: OpsGenie
    config:
      channelType: opsgenie
      apiKey: ${OPSGENIE_API_KEY}
      region: us
```

| Config field  | Required | Description                   |
| ------------- | -------- | ----------------------------- |
| `channelType` | Yes      | Always `opsgenie`             |
| `apiKey`      | Yes      | OpsGenie API integration key  |
| `region`      | —        | OpsGenie region: `us` or `eu` |

### Discord

```yaml theme={null}
alertChannels:
  - name: Discord Alerts
    config:
      channelType: discord
      webhookUrl: ${DISCORD_WEBHOOK_URL}
      mentionRoleId: "123456789"
```

| Config field    | Required | Description                |
| --------------- | -------- | -------------------------- |
| `channelType`   | Yes      | Always `discord`           |
| `webhookUrl`    | Yes      | Discord webhook URL        |
| `mentionRoleId` | —        | Discord role ID to mention |

### Microsoft Teams

```yaml theme={null}
alertChannels:
  - name: Teams Channel
    config:
      channelType: teams
      webhookUrl: ${TEAMS_WEBHOOK_URL}
```

| Config field  | Required | Description                |
| ------------- | -------- | -------------------------- |
| `channelType` | Yes      | Always `teams`             |
| `webhookUrl`  | Yes      | Teams incoming webhook URL |

### Email

```yaml theme={null}
alertChannels:
  - name: Ops Email
    config:
      channelType: email
      recipients:
        - ops@example.com
        - oncall@example.com
```

| Config field  | Required | Description                         |
| ------------- | -------- | ----------------------------------- |
| `channelType` | Yes      | Always `email`                      |
| `recipients`  | Yes      | List of email addresses (non-empty) |

### Webhook

```yaml theme={null}
alertChannels:
  - name: Custom Webhook
    config:
      channelType: webhook
      url: https://webhook.site/00000000-0000-0000-0000-000000000000
      signingSecret: ${WEBHOOK_SECRET}
      customHeaders:
        X-Source: devhelm
```

| Config field    | Required | Description                                  |
| --------------- | -------- | -------------------------------------------- |
| `channelType`   | Yes      | Always `webhook`                             |
| `url`           | Yes      | HTTP endpoint URL                            |
| `signingSecret` | —        | HMAC signing secret for payload verification |
| `customHeaders` | —        | Custom headers sent with each request        |

### Other channel types

Additional `channelType` values are accepted: `telegram`, `google_chat`, `pushover`, `mattermost`, `splunk_oncall`, `pushbullet`, `linear`, `incident_io`, `rootly`, `zapier`, `datadog`, `jira`, and `gitlab`. Their config fields mirror the dashboard form for each integration — see [Integrations](/integrations/overview) for the required fields per channel.

## Referencing channels

Monitors and notification policies reference channels by name:

```yaml theme={null}
monitors:
  - name: API Health
    type: HTTP
    config:
      url: https://api.example.com/health
      method: GET
    alertChannels: [Slack Alerts, PagerDuty On-Call]

notificationPolicies:
  - name: Critical Alerts
    escalation:
      steps:
        - channels: [Slack Alerts]
        - channels: [PagerDuty On-Call]
          delayMinutes: 5
```

## Using environment variables

Store sensitive values (webhook URLs, API keys, routing keys) as environment variables and reference them with `${VAR}` syntax. Set them in your shell or CI secrets — they're resolved at deploy time.

## Next steps

<CardGroup cols={2}>
  <Card title="Notification policies" icon="bell" href="/mac/yaml/notification-policies">
    Route incidents through escalation chains.
  </Card>

  <Card title="Integrations" icon="puzzle-piece" href="/integrations/overview">
    Setup guides for each channel type.
  </Card>
</CardGroup>