Notifications Setup Guide

Controlinfra sends real-time alerts when drift is detected, scans fail, runners go offline, guardrails trigger, and more. Configure one or more notification channels in Settings > Integrations > Notifications.

Available Channels

Channel	Setup	Alert Types
Slack	Webhook URL or Bot Token	All events
Microsoft Teams	Incoming Webhook	All events
PagerDuty	Events API v2 Routing Key	Critical drift, runner offline
Custom Webhooks	HTTP endpoint + HMAC secret	Configurable per event
Email	Alert Groups (member emails)	Guardrail alerts
In-App	Enabled by default	All events

---

Slack Integration

Option 1: Incoming Webhook (Recommended)

1. Go to Settings > Integrations > Notifications
2. Click the Slack card
3. Create a Slack Incoming Webhook:
   • Visit api.slack.com/messaging/webhooks
   • Choose your workspace and channel
   • Copy the webhook URL
4. Paste the webhook URL and click Save
5. Click Test to send a test message

Option 2: Bot Token (Per-Channel Routing)

For routing different alert types to different Slack channels:

1. Create a Slack App at api.slack.com/apps
2. Add the chat:write and channels:read OAuth scopes
3. Install the app to your workspace
4. Copy the Bot User OAuth Token (xoxb-...)
5. Paste in the Bot Token field in Controlinfra
6. Select which channel receives which alert type

Notification Preferences

Toggle which events trigger Slack notifications:

• Critical drift detected — High/critical severity drift
• Scan failed — Repository scan errors
• Runner offline — Self-hosted runner disconnected
• PR merged — Auto-created fix PR merged
• Discovery completed — Cloud discovery scan finished
• Discovery failed — Cloud discovery scan errors
• Guardrail alert — Guardrail rule triggered

---

Microsoft Teams Integration

1. In your Teams channel, click ... > Connectors > Incoming Webhook
2. Name it "Controlinfra" and copy the webhook URL
3. In Controlinfra, go to Settings > Integrations > Notifications
4. Click the Teams card
5. Paste the webhook URL and click Save
6. Click Test to verify

Teams notifications include:

• Color-coded cards by severity
• Resource details and metadata
• "View in Controlinfra" action button

---

PagerDuty Integration

1. In PagerDuty, create a new Service or use an existing one
2. Add an Events API v2 integration
3. Copy the Integration Key (routing key)
4. In Controlinfra, go to Settings > Integrations > Notifications
5. Click the PagerDuty card
6. Paste the routing key and click Save

Severity Mapping

Controlinfra Event	PagerDuty Severity
Runner offline	Critical
Scan failed	Error
Drift detected	Warning
Drift watch alert	Warning
Scan completed	Info
Discovery completed	Info

PagerDuty automatically deduplicates incidents using the resource ID.

---

Custom Webhooks

Send structured JSON payloads to any HTTP endpoint.

1. Go to Settings > Integrations > Notifications > Webhooks
2. Click Add Webhook
3. Configure:
   • Name — Descriptive label
   • URL — Your HTTPS endpoint
   • Secret (optional) — HMAC-SHA256 signing key
   • Events — Select which events trigger this webhook

Payload Format

{
  "event": "drift.detected",
  "timestamp": "2026-04-05T12:00:00.000Z",
  "data": {
    "title": "Critical drift detected",
    "message": "aws_security_group drift found in prod-infra",
    "type": "drift_critical",
    "metadata": {
      "driftId": "...",
      "scanId": "...",
      "severity": "critical",
      "resourceType": "aws_security_group"
    }
  }
}

Signature Verification

If a secret is configured, each request includes an X-Webhook-Signature header:

X-Webhook-Signature: sha256=<hex_digest>

Verify by computing HMAC-SHA256(secret, request_body) and comparing.

Available Events

• scan.completed, scan.failed
• drift.detected, drift.resolved, drift.fix_generated, drift.pr_created
• discovery.completed
• runner.offline

---

Per-Watch Notifications (Drift Watch)

Individual drift watches can be configured with specific notification preferences:

1. Click a watched resource to open the detail panel
2. Scroll to Watch Settings > Notifications
3. Configure:
   • Channels — Select which of your configured channels receive alerts for this watch
   • Severity Threshold — Only notify when drift severity meets this level (Critical, High, Medium, All)
   • Notify on Clean — Alert when resource returns to baseline
   • Notify on Error — Alert when check fails

This allows fine-grained control — critical production resources can alert on all channels, while development resources only alert on Slack.

---

Notification Routing Rules

Routing rules let you direct specific event types to specific notification channels automatically. Instead of sending every alert everywhere, you can create targeted rules.

Creating a Routing Rule

1. Go to Settings > Integrations > Notifications > Routing Rules
2. Click Add Rule
3. Configure:
   • Event types -- Select one or more events (e.g., drift.detected, scan.failed, runner.offline)
   • Severity filter -- Optionally restrict to a minimum severity (Critical, High, Medium, All)
   • Destination channels -- Choose which configured channels receive matching events (Slack, Teams, PagerDuty, Webhook, or Alert Group)
4. Click Save

Example Rules

Rule Name	Events	Severity	Destination
Critical to PagerDuty	drift.detected	Critical only	PagerDuty
All scan failures to Slack	scan.failed	All	Slack #ops-alerts
Discovery alerts to email	discovery.completed, discovery.failed	All	Platform Engineers (Alert Group)

Routing rules are evaluated in order. An event can match multiple rules and be sent to multiple channels.

For more details, see the Notification Routing Guide.

---

Email Notifications (Alert Groups)

Email notifications are routed through Alert Groups — named lists of email addresses.

1. Go to Settings > Integrations > Notifications > Alert Groups
2. Create a group (e.g., "Security Team", "Platform Engineers")
3. Add member email addresses
4. When configuring a guardrail's alert delivery or a notification routing rule, select which groups receive emails

---

Troubleshooting

Slack notifications not arriving

• Verify the webhook URL is correct (test button should succeed)
• Check that the notification type is enabled in preferences
• Ensure the Slack channel hasn't been archived

PagerDuty incidents not triggering

• Verify the routing key matches your service
• Check that the service has an escalation policy assigned
• PagerDuty deduplicates — check for existing open incidents

Webhook delivery failures

• Ensure your endpoint returns 2xx within 10 seconds
• Check the X-Webhook-Signature verification logic
• View delivery stats in Settings > Webhooks > your webhook