# Notification Routes

{% hint style="info" %}
This capability is only available to BYOC deployments. Check out our [pricing page](https://www.groundcover.com/pricing) for more information about subscription plans and the available deployment modes.
{% endhint %}

{% hint style="info" %}
Editor permissions are required for creating and editing Notification Routes.\
Reader permissions may list the existing Notification Routes.
{% endhint %}

### How It Works

1. **Scope**: A gcQL query that filters which monitors' issues will trigger this route
2. **Rules**: Define what happens when an issue is in a specific state (Firing or Resolved)
3. [**Connected Apps**](/integrations/connected-apps.md): Choose where to send the notification (e.g., Slack Webhook, Pagerduty, etc)

### Prerequisites

Before creating notification routes, set up your Connected Apps in **Settings → Connected-Apps**.

### Create a Notification Route

1. Go to **Monitors → Notification Routes**
2. Click **Create Notification Route**
3. Complete the wizard:

#### Step 1: Route Name

Give your route a descriptive name (e.g., `prod-critical-alerts`, `infra-team-notifications`).

#### Step 2: Scope Monitors

Define which monitors this route applies to using gcQL on:

1. The grouping labels defined in the query
2. The custom labels
3. The Monitor's metadata such as the name or severity

**Examples:**

* `env:prod` — All monitors with grouping key 'env' and possible value of 'prod'
* `env:prod AND severity:S1` — Only critical production alerts
* `team:platform` — Monitors with a custom label for the platform team
* `*:*` — To match all monitors

#### Step 3: Rules

Rules define what happens when a scoped monitor's issue changes state.

Each rule has:

* **Status**: When to trigger — `Firing` (issue is active) or `Resolved` (issue cleared)
* **Connected Apps**: Where to send the notification

**Example setup:**

* When **Firing or Resolved** → Send to `#prod-alerts` Slack channel
* When **Firing** (only) → Send to `Pagerduty` service directory

Click **Add Rule** to create multiple rules with different status/destination combinations.

#### Re-notification Interval

Configure how long to wait before sending another notification while an alert is still firing.

Options: 1m, 5m, 10m, 30m, 1h, 2h, 4h, 8h, 12h, 1d, 2d

This prevents notification fatigue from long-running alerts.

### Managing Notification Routes

The Notification Routes page shows all your routes with:

* **Name**: Route identifier
* **Scope**: The gcQL query defining which monitors are affected
* **Connected Apps**: Summary of destinations by type
* **Creator**: Who created the route

#### Edit, Duplicate, or Delete

Hover over any row to access the action menu:

* **Edit**: Modify the route configuration
* **Duplicate**: Create a copy as a starting point
* **Delete**: Remove the route

### Example Use Cases

#### Route Critical Production Alerts to PagerDuty and Slack

```
Name: prod-critical-pagerduty
Scope: env:prod AND severity:S1

Rules:
- When Firing → PagerDuty On-Call
- When Firing or Resolved → #critical-alerts (Slack)
```

#### Separate Routes by Team

```
Name: platform-team-alerts
Scope: team:platform

Rules:
- When Firing → #platform-alerts (Slack)
- When Resolved → #platform-alerts (Slack)
```

```
Name: backend-team-alerts
Scope: team:backend

Rules:
- When Firing → #backend-alerts (Slack)
- When Resolved → #backend-alerts (Slack)
```

#### Development Alerts — Firing Only

```
Name: dev-notifications
Scope: env:dev

Rules:
- When Firing → #dev-alerts (Slack)
```

### Testing Notifications

To test your notification configuration before enabling it on production monitors:

1. **Test Connected Apps directly**: In Settings → Connected Apps, click the "Test" button on any configured app to send a test notification with sample data
2. **Test from a monitor**: Open any monitor, click the "Test" button to send a test notification using that monitor's actual payload

{% hint style="info" %}
The test button in Connected Apps requires Admin permissions. The test button within monitors works for Editor permissions and respects your RBAC data scope.
{% endhint %}

### Re-notification Behavior

Understanding how re-notification intervals work:

* The re-notification timer starts when the first notification is sent
* If an alert **resolves and fires again** within the re-notification window, and the fingerprint is the same, the timer continues (no new notification)
* The `renotification_count` field in payloads starts at 0 for the first notification and increments with each re-notification
* When an alert resolves, the counter resets for the next firing cycle

### Permissions

| Action                          | Required Permission |
| ------------------------------- | ------------------- |
| Create/Edit Notification Routes | Editor              |
| View Notification Routes        | Reader              |
| Create/Edit Connected Apps      | Admin               |
| Test Connected Apps             | Admin               |
| Test from Monitor               | Editor              |

### How Routes Apply to Monitors

Notification Routes apply **automatically** based on label matching. You do not need to edit existing monitors to use routes:

1. Routes match monitors based on the scope query (gcQL)
2. When a monitor fires, all routes whose scope matches the monitor's labels will trigger
3. Multiple routes can match the same monitor

### Troubleshooting

#### Notifications not being sent

1. Verify the scope query matches your monitor's labels
2. Check that the Connected App is properly configured (use Test button)
3. Review `dispatch-center` traces in groundcover for delivery errors
4. Ensure the monitor has transitioned state (not just hovering at threshold)

#### Wrong time range in issue links

If clicking notification links shows "Last 5 minutes" instead of the actual alert time, this typically affects legacy Workflow-based notifications. Migrate to Notification Routes for proper time range handling.

#### Debugging notification delivery

Filter traces by `workload:dispatch-center` to see notification delivery attempts and any errors.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.groundcover.com/use-groundcover/monitors/notification-routes.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.