Skip to main content
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:
  1. Step 1 executes — the configured channels are notified
  2. Delay — if the next step has a delayMinutes value, the chain waits
  3. Acknowledgment check — if the current step has requireAck: true and someone acknowledged, the chain stops
  4. Step 2 executes — the next set of channels is notified
  5. Repeat — continues through all steps until the chain completes or the incident resolves

​
Step fields

Each step in the chain has the following configuration:
FieldTypeRequiredDescription
delayMinutesintegerNoMinutes to wait before executing this step (0 = immediate, minimum 0)
channelIdsUUID[]YesAlert channels to notify (at least one required)
requireAckbooleanNoIf true, acknowledgment is required before advancing to the next step
repeatIntervalSecondsintegerNoRe-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:
ValueBehavior
notify_all_stepsAll steps that were notified receive a resolution message
notify_current_stepOnly the step that was active when the incident resolved gets notified
silentNo resolution notification is sent
Stateful integrations (PagerDuty, OpsGenie) 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:
ValueBehavior
restart_from_beginningThe escalation chain starts over from step 1
restart_from_currentThe chain resumes from the step that was active when the incident resolved

​
Escalation chain fields

FieldTypeRequiredDescription
stepsEscalationStep[]YesOrdered steps (at least one required)
onResolvestringNoAction when incident resolves
onReopenstringNoAction 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.