Notification Routing Setup Guide

A step-by-step guide for creating notification routing rules that direct specific events to specific channels.

Before You Start

Notification routing requires at least one notification channel already configured. If you have not set up channels yet, see the Notifications Setup Guide first.

Supported Channels

Channel	Setup Location
Slack	Settings > Integrations > Notifications > Slack
Microsoft Teams	Settings > Integrations > Notifications > Teams
PagerDuty	Settings > Integrations > Notifications > PagerDuty
Email (Alert Groups)	Settings > Integrations > Notifications > Alert Groups
Custom Webhooks	Settings > Integrations > Notifications > Webhooks

---

Step 1: Navigate to Notification Routing

1. Open Settings from the sidebar
2. Click Integrations
3. Select the Notification Routing tab

You will see a list of existing routes (if any) and a Create Route button.

---

Step 2: Create a New Route

1. Click Create Route
2. The route editor modal opens

Name Your Route

Enter a descriptive name that makes the route's purpose clear at a glance:

• "Critical drift to PagerDuty"
• "GCP scan failures to platform-team Slack"
• "All guardrail alerts to security email group"

Add a Description (Optional)

Use the description field to document why the route exists or who it serves.

---

Step 3: Configure Conditions

Conditions determine which events trigger this route. Set one or more of the following:

Event Type

Select which event types this route handles:

Event Type	When It Fires
Drift detected	New drift found during a scan
Scan completed	A scan finishes successfully
Scan failed	A scan encounters an error
Runner offline	A self-hosted runner disconnects
Discovery completed	Cloud discovery scan finishes
Discovery failed	Cloud discovery scan errors
Guardrail triggered	A guardrail rule is violated
PR created	An auto-fix pull request is opened
PR merged	An auto-fix pull request is merged

Severity

Filter by drift severity level:

• Critical — Only critical severity events
• High — High severity events
• Medium — Medium severity events
• Low — Low severity events
• Any — All severity levels (default)

Provider

Filter by cloud provider:

• AWS
• Azure
• GCP
• Any — All providers (default)

Resource Type

Enter a resource type string to match (e.g., aws_security_group). Leave blank to match all resource types.

TIP

All conditions are combined with AND logic. An event must match every condition for the route to fire. Leave conditions set to Any if you do not need to filter on that field.

---

Step 4: Select Destination Channel

Choose one or more channels where matching events should be sent:

1. Click Add Destination
2. Select a channel type (Slack, Teams, PagerDuty, Email, Webhook)
3. If the channel type supports multiple targets (e.g., Slack with Bot Token), select the specific channel

You can add multiple destinations to a single route. For example, send critical drift alerts to both PagerDuty and a Slack channel.

---

Step 5: Test the Route

Before relying on a route in production, verify it works:

1. Click Test on the route row in the routing table
2. Controlinfra sends a synthetic test event matching the route's conditions
3. Check the destination channel for the test notification

Test notifications are clearly labeled with a [TEST] prefix so they are not confused with real events.

WARNING

PagerDuty test events are sent with info severity to avoid triggering real pages or waking on-call engineers.

---

Step 6: Enable or Disable Routes

Each route has an Enabled toggle:

• Enabled (default) — The route actively processes events
• Disabled — The route is paused but its configuration is preserved

Toggle the switch in the route list to change status. This is useful for temporarily silencing a noisy route during maintenance without deleting it.

---

Example: Route Critical Drifts to PagerDuty

This example creates a route that pages the on-call engineer when critical drift is detected in any provider.

Setting	Value
Name	Critical drift escalation
Event Type	Drift detected
Severity	Critical
Provider	Any
Resource Type	(blank — all types)
Destination	PagerDuty

Result: When a scan detects critical-severity drift, PagerDuty receives an alert that creates an incident and pages the on-call.

---

Example: Route Low Severity to Slack

This example sends low-severity drift notifications to a low-priority Slack channel.

Setting	Value
Name	Low severity to Slack
Event Type	Drift detected
Severity	Low
Provider	Any
Resource Type	(blank)
Destination	Slack (#infra-low-priority)

Result: Low-severity drift stays visible without cluttering the main alerts channel.

---

Example: Route GCP Failures to Email

Setting	Value
Name	GCP failures to platform team
Event Type	Scan failed
Severity	Any
Provider	GCP
Resource Type	(blank)
Destination	Email (Platform Engineers group)

Result: GCP scan failures are emailed to the platform engineering team's alert group.

---

How Route Evaluation Works

When an event occurs:

1. Controlinfra checks all enabled routing rules
2. Every route whose conditions match the event fires independently
3. The event is sent to each matching route's destination(s)
4. If no routes match, the event falls back to basic notification preferences

Routes do not have priority ordering. Multiple routes can fire for the same event, which is useful for sending to multiple channels at different severity thresholds.

---

Managing Routes

Edit an Existing Route

Click the pencil icon on any route to re-open the editor modal. Changes apply immediately after saving.

Delete a Route

Click the trash icon and confirm deletion. This action is permanent.

Bulk Operations

Use the checkboxes in the route list to select multiple routes, then use the bulk action dropdown to Enable, Disable, or Delete selected routes.

---

Troubleshooting

Route not firing

• Verify the route is Enabled
• Check that all conditions match the event (conditions use AND logic)
• Ensure the destination channel is properly configured and active
• Use the Test button to verify the destination is reachable

Duplicate notifications

• Multiple routes can match the same event. Review your routes for overlapping conditions
• Basic notification preferences also fire unless the event type is toggled off there

Test succeeds but real events do not arrive

• Confirm the event type matches exactly (e.g., "Drift detected" vs. "Scan completed")
• Check severity and provider filters are not too restrictive

Next Steps

• Notification Routing Feature - Feature overview
• Notifications Setup - Configure channels
• Drift Watch - Per-resource watch notifications