> ## Documentation Index
> Fetch the complete documentation index at: https://docs.devhelm.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Escalation Chains

> Build multi-step escalation chains in DevHelm with delays, acknowledgment, and repeat rules

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:

| 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:

```json theme={null}
{
  "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:

```json theme={null}
{
  "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:

```json theme={null}
{
  "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

```bash theme={null}
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                                     |

<Note>
  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.
</Note>

## Reopen behavior

The `onReopen` field controls what happens when a resolved incident [reopens](/incidents/timeline#reopening):

| 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          |

<Note>
  Escalation chains are embedded in notification policies, not managed as separate resources. Create and update them as part of the [notification policy](/alerting/notification-policies) configuration.
</Note>

## Next steps

<CardGroup cols={2}>
  <Card title="Notification policies" icon="filter" href="/alerting/notification-policies">
    Configure match rules that trigger escalation chains.
  </Card>

  <Card title="Alert channels" icon="plug" href="/alerting/channels">
    Set up the channel destinations referenced by escalation steps.
  </Card>

  <Card title="Tiered escalation guide" icon="wrench" href="/guides/tiered-escalation">
    Step-by-step guide for building multi-tier escalation.
  </Card>
</CardGroup>