Escalation Chains

Escalation chains define a sequence of alert steps that execute when a notification policy matches an incident. Each step can notify different channels, wait for acknowledgment, and repeat until someone responds.

How escalation works

When a notification policy matches an incident, its escalation chain begins executing:

Step 1 executes — the configured channels are notified
Delay — if the next step has a delayMinutes value, the chain waits
Acknowledgment check — if the current step has requireAck: true and someone acknowledged, the chain stops
Step 2 executes — the next set of channels is notified
Repeat — continues through all steps until the chain completes or the incident resolves

Step fields

Each step in the chain has the following configuration:

Field	Type	Required	Description
`delayMinutes`	integer	No	Minutes to wait before executing this step (0 = immediate, minimum 0)
`channelIds`	UUID[]	Yes	Alert channels to notify (at least one required)
`requireAck`	boolean	No	If true, acknowledgment is required before advancing to the next step
`repeatIntervalSeconds`	integer	No	Re-notify at this interval until acknowledged (minimum 1 second)

Example chains

Simple — Slack then PagerDuty

Notify Slack immediately. If no one acknowledges within 10 minutes, page on-call via PagerDuty:

{
  "steps": [
    {
      "delayMinutes": 0,
      "channelIds": ["<slack-channel-id>"],
      "requireAck": true
    },
    {
      "delayMinutes": 10,
      "channelIds": ["<pagerduty-channel-id>"],
      "requireAck": true,
      "repeatIntervalSeconds": 300
    }
  ],
  "onResolve": "notify_all_steps",
  "onReopen": "restart_from_beginning"
}

Immediate multi-channel

Notify Slack and email simultaneously with no escalation:

{
  "steps": [
    {
      "delayMinutes": 0,
      "channelIds": ["<slack-channel-id>", "<email-channel-id>"]
    }
  ],
  "onResolve": "notify_all_steps"
}

Three-tier escalation

Team channel → engineering lead → management with increasing urgency:

{
  "steps": [
    {
      "delayMinutes": 0,
      "channelIds": ["<team-slack-id>"],
      "requireAck": true
    },
    {
      "delayMinutes": 15,
      "channelIds": ["<lead-pagerduty-id>"],
      "requireAck": true,
      "repeatIntervalSeconds": 300
    },
    {
      "delayMinutes": 30,
      "channelIds": ["<management-email-id>"]
    }
  ],
  "onResolve": "notify_all_steps",
  "onReopen": "restart_from_beginning"
}

Acknowledgment

When a step has requireAck: true, the escalation chain pauses at that step until someone acknowledges the notification. Acknowledgment can happen through:

External system — acknowledging the PagerDuty or OpsGenie alert
DevHelm API — calling the acknowledge endpoint on the notification dispatch

curl -X POST https://api.devhelm.io/api/v1/notification-dispatches/<dispatch-id>/acknowledge \
  -H "Authorization: Bearer $DEVHELM_API_TOKEN"

If repeatIntervalSeconds is set, the step re-notifies at that interval until acknowledged or the incident resolves.

Resolution behavior

The onResolve field controls what happens when the incident resolves:

Value	Behavior
`notify_all_steps`	All steps that were notified receive a resolution message
`notify_current_step`	Only the step that was active when the incident resolved gets notified
`silent`	No resolution notification is sent

Stateful integrations (PagerDuty, OpsGenie, Splunk On-Call, Incident.io, Rootly, GitLab) always close their external alerts on resolution, even when onResolve is silent. The silent setting only suppresses DevHelm’s resolution notification.

Reopen behavior

The onReopen field controls what happens when a resolved incident reopens:

Value	Behavior
`restart_from_beginning`	The escalation chain starts over from step 1
`restart_from_current`	The chain resumes from the step that was active when the incident resolved

Escalation chain fields

Field	Type	Required	Description
`steps`	EscalationStep[]	Yes	Ordered steps (at least one required)
`onResolve`	string	No	Action when incident resolves
`onReopen`	string	No	Action when incident reopens

Escalation chains are embedded in notification policies, not managed as separate resources. Create and update them as part of the notification policy configuration.

Next steps

Notification policies

Configure match rules that trigger escalation chains.

Alert channels

Set up the channel destinations referenced by escalation steps.

Tiered escalation guide

Step-by-step guide for building multi-tier escalation.

Getting Started

Monitoring as Code

Monitoring

Incidents

Alerting

Status Data

Platform

Common Patterns

Escalation Chains

How escalation works

Step fields

Example chains

Simple — Slack then PagerDuty

Immediate multi-channel

Three-tier escalation

Acknowledgment

Resolution behavior

Reopen behavior

Escalation chain fields

Next steps

Notification policies

Alert channels

Tiered escalation guide

​How escalation works

​Step fields

​Example chains

​Simple — Slack then PagerDuty

​Immediate multi-channel

​Three-tier escalation

​Acknowledgment

​Resolution behavior

​Reopen behavior

​Escalation chain fields

​Next steps

Notification policies

Alert channels

Tiered escalation guide

How escalation works

Step fields

Example chains

Simple — Slack then PagerDuty

Immediate multi-channel

Three-tier escalation

Acknowledgment

Resolution behavior

Reopen behavior

Escalation chain fields

Next steps