Notification Policies#

Notification policies define which shared notification channels receive events for a service.

They are useful when several routes belong to the same logical service and should use the same notification rules. Instead of copying channel lists to every route, assign one notification policy to the service and configure the route to use it.

How notification policies work#

A notification policy belongs to one team and contains ordered rules.

Each rule defines:

• the event types it handles;
• optional alert matchers;
• one or more notification channels;
• whether evaluation continues after the rule matches;
• whether the rule is enabled.

Rules are evaluated by position, starting with the lowest position.

When a rule matches, its channels are added to the delivery targets. Evaluation then stops unless Continue matching is enabled for that rule.

Duplicate channels are removed before delivery.

Event types#

A rule can handle one or more event types:

Acknowledged and resolved events do not select channels again. IncidentRelay updates the messages that were created by earlier deliveries.

This means that changing or removing a notification policy does not prevent IncidentRelay from updating an already delivered message when the alert is acknowledged or resolved.

Matchers#

Notification policy rules use the same matcher format as service match rules.

The shared editor can suggest label names and values from recent team alerts. See Alert Matchers.

An empty matcher object matches every alert:

Copy{}

Match by severity:

Copy{
  "severity": "critical"
}

Match by priority:

Copy{
  "priority": ["p1", "p2"]
}

Match by labels:

Copy{
  "labels": {
    "environment": "production",
    "namespace": {
      "regex": "^payments-"
    }
  }
}

Match by service or team fields:

Copy{
  "fields": {
    "service.slug": "payments-api",
    "team.slug": "platform"
  }
}

A catch-all rule is commonly placed last so that alerts not handled by earlier rules still receive a notification.

Route channel modes#

A route controls how IncidentRelay combines its own channels with the matched service notification policy.

Existing routes default to route_only, so enabling notification policies does not change their current delivery behavior.

No implicit fallback#

service_policy does not fall back to route channels.

If the matched service has no policy, the policy is disabled, or no enabled rule matches the event, no shared channel is selected by that route mode.

Use service_policy_plus_route when route channels should remain a fallback or must always receive the event.

Personal notification rules, including browser push rules, are evaluated separately from shared channel policies.

Configure a notification policy#

• Open Services → Notification Policies.
• Select New policy.
• Choose the owning team.
• Enter a name and optional description.
• Save the policy.
• Open the policy action menu and select Rules.
• Add rules in the required evaluation order.
• Select event types, matchers and channels for each rule.
• Save each rule.

An enabled rule must contain at least one notification channel. A disabled rule may be saved without channels.

Assign a policy to a service#

• Open Services → Service Catalog.
• Create or edit a service.
• Select a value in Notification policy.
• Save the service.

A service can only use an enabled notification policy owned by the same team.

A policy assigned to a service cannot be deleted. Remove the policy from all services before deleting it.

Configure a route#

• Open Routes.
• Create or edit a route.
• Select Notification channel source.
• Choose one of:
• Route channels only;
• Service notification policy;
• Service policy + route channels.
• Save the route.

For service policy modes, the alert group must have a service. The service can come from the route default service or from a matching service rule.

Example: critical alerts and a catch-all rule#

Policy rules:

• Critical alerts
• event types: notification, reminder, escalation;
• matcher: {"severity": "critical"};
• channels: Mattermost and Telegram;
• continue matching: disabled.

• Default alerts
• event types: notification;
• matcher: {};
• channels: Email;
• continue matching: disabled.

A critical alert uses Mattermost and Telegram and stops at the first rule. A non-critical initial alert skips the first rule and uses Email.

Example: combine several matching rules#

Policy rules:

• Production alerts
• matcher: {"labels": {"environment": "production"}};
• channels: Operations Mattermost;
• continue matching: enabled.

• Critical alerts
• matcher: {"severity": "critical"};
• channels: Emergency Telegram;
• continue matching: disabled.

A critical production alert receives both Mattermost and Telegram delivery. A non-critical production alert receives only Mattermost delivery.

Disabled resources#

IncidentRelay ignores:

• disabled policies;
• disabled rules;
• disabled or deleted channels.

A policy rule that does not include the current event type is skipped.

Recommended setup#

combined.

configuration.

events.

• Keep a catch-all rule last when every event should reach a shared channel.
• Use specific rules before generic rules.
• Use continue_matching only when channels from several rules should be
• Use service_policy when the service policy is the authoritative delivery
• Use service_policy_plus_route when route-level channels must also receive
• Test reminder and escalation rules separately from initial notification rules.