---
title: 'Notification Channels'
description: 'How to create and manage notification channels for Slack, email, webhook, PagerDuty, and ServiceNow alerts.'
section: 'Guides'
canonical_url: 'https://yorkermonitoring.com/docs/guides/notification-channels'
---

# Notification Channels

Notification channels define where alerts are sent. Yorker supports five channel types: **Slack**, **email**, **webhook**, **PagerDuty**, and **ServiceNow**. Channels are shared across your team and can be referenced by any alert rule or SLO.

## Channel Types

### Slack

Posts alert notifications to a Slack channel via an incoming webhook.

```yaml
alertChannels:
  ops-slack:
    type: slack
    webhookUrl: "{{secrets.SLACK_WEBHOOK_URL}}"
```

To set up a Slack webhook, create an [Incoming Webhook](https://api.slack.com/messaging/webhooks) in your Slack workspace and use the generated URL.

### Email

Sends alert notifications to one or more email addresses.

```yaml
alertChannels:
  on-call-email:
    type: email
    addresses:
      - oncall@example.com
      - sre-team@example.com
```

At least one address is required.

### Webhook

Sends an HTTP request to any URL. Use this for Opsgenie, custom integrations, or any service that accepts webhooks. For PagerDuty and ServiceNow, prefer the dedicated channel types below: they speak the native APIs, dedupe incidents with each platform's own keying (so a recurring Yorker alert updates the existing PD/SNOW record instead of creating a new one), and follow each platform's lifecycle event semantics.

```yaml
alertChannels:
  opsgenie:
    type: webhook
    url: "{{secrets.OPSGENIE_WEBHOOK_URL}}"
    method: POST
    headers:
      Authorization: "GenieKey {{secrets.OPSGENIE_KEY}}"
```

| Field | Default | Description |
|---|---|---|
| `url` | *(required)* | Webhook endpoint URL. |
| `method` | `POST` | HTTP method. |
| `headers` | *(none)* | Optional headers for authentication. |

### PagerDuty

Speaks the PagerDuty Events API v2 directly. See the [PagerDuty integration guide](/docs/integrations/pagerduty) for the full setup: routing key + region selection, plus how Yorker incident lifecycle events (opened, acknowledged, auto_resolved, closed, reopened) map to PagerDuty event actions.

```yaml
alertChannels:
  pagerduty-oncall:
    type: pagerduty
    routingKey: "{{secrets.PAGERDUTY_ROUTING_KEY}}"
    serviceRegion: us  # or "eu" for events.eu.pagerduty.com
```

| Field | Default | Description |
|---|---|---|
| `routingKey` | *(required)* | PagerDuty Events API v2 integration key. |
| `serviceRegion` | `us` | `us` for events.pagerduty.com, `eu` for events.eu.pagerduty.com. |

### ServiceNow

Creates and updates ServiceNow incidents via the Table API. See the [ServiceNow integration guide](/docs/integrations/servicenow) for the full setup: instance authentication, Yorker incident-event mapping to ServiceNow Table API actions, plus field and severity mappings on the resulting incident records.

```yaml
alertChannels:
  servicenow-prod:
    type: servicenow
    instanceUrl: "https://acme.service-now.com"
    username: "{{secrets.SNOW_USER}}"
    password: "{{secrets.SNOW_PASSWORD}}"
    assignmentGroup: "Platform Oncall"  # optional
```

| Field | Default | Description |
|---|---|---|
| `instanceUrl` | *(required)* | Full ServiceNow instance URL (e.g. `https://acme.service-now.com`). |
| `username` | *(required)* | ServiceNow account with permission to create incidents. |
| `password` | *(required)* | ServiceNow account password or OAuth token. Treated as a secret at rest. |
| `assignmentGroup` | *(none)* | Optional group name (maps to `sys_user_group.name`) for new incidents. |

## Create channels in the Web UI

1. Navigate to **Settings > Notification Channels**.
2. Click **Create Channel**.
3. Select the channel type (Slack, Email, or Webhook).
4. Fill in the required fields.
5. Click **Save**.

The Web UI currently supports Slack, Email, and Webhook channel types. **PagerDuty** and **ServiceNow** channels must be defined via YAML (see below) or the [REST API](/docs/reference/api). UI editor support for those channel types is planned for a future release.

Channels created in the UI and via the CLI are the same underlying resource. The CLI's `yorker deploy` detects and diffs against channels created through the UI.

## Define channels in YAML

Add an `alertChannels` block at the top level of `yorker.config.yaml`:

```yaml
alertChannels:
  ops-slack:
    type: slack
    webhookUrl: "{{secrets.SLACK_WEBHOOK_URL}}"

  on-call-email:
    type: email
    addresses:
      - oncall@example.com

  pagerduty-oncall:
    type: pagerduty
    routingKey: "{{secrets.PAGERDUTY_ROUTING_KEY}}"

  servicenow-prod:
    type: servicenow
    instanceUrl: "https://acme.service-now.com"
    username: "{{secrets.SNOW_USER}}"
    password: "{{secrets.SNOW_PASSWORD}}"
```

### Reference channels in alerts

Use the `@channel-name` syntax to attach a channel to an alert rule:

```yaml
monitors:
  - name: API Health
    type: http
    url: https://api.example.com/health
    alerts:
      - conditions:
          - type: consecutive_failures
            count: 3
        channels:
          - "@ops-slack"
          - "@on-call-email"
```

### Reference channels in SLOs

SLOs can also reference channels for burn rate alerts:

```yaml
slos:
  - name: API Availability
    monitor: API Health
    target: "99.9%"
    window: 30d
    channels:
      - "@ops-slack"
```

## Deploy ordering

When you run `yorker deploy`, channels are created/updated **before** alerts and SLOs (phase 0), and deleted **after** all references are removed (phase Z). This ensures channels always exist when alerts or SLOs reference them.

## Customize incident notification templates

Slack, email, and webhook channels support per-event template overrides that let you replace Yorker's default payload with your own Handlebars-rendered markup. The in-app editor at **Settings > Notification Channels > Templates** gives you:

- A Handlebars editor with channel-appropriate syntax highlighting (JSON for Slack/webhook, HTML for email)
- A live preview rendered against six canonical incident fixtures (single HTTP failure, multi-location burst, browser check, MCP, and more)
- A library of starters and curated examples you can apply with one click, plus a diff view against the currently saved template
- **Send test**: dispatches the current saved template to the real channel with the selected fixture (60-second cooldown per channel)

See the [Incidents concepts page](/docs/concepts/incidents#user-editable-templates) for the render context and fallback semantics. Per-channel examples and helper reference live on each integration page: [Slack](/docs/integrations/slack#template-overrides), [Email](/docs/integrations/email#template-overrides), [Webhook](/docs/integrations/webhook#template-overrides).

PagerDuty and ServiceNow template overrides are authored through the REST API only; UI editor support for those channel types is planned for a future release.

## Manage channels via API

Channels can also be managed through the REST API. See the [REST API reference](/docs/reference/api) for endpoints.