Escalation Policies

An escalation policy notifies more people, step by step, while an incident is open and nobody has acknowledged it. For example: the on-call person first, their backup 15 minutes later, then the team lead.

Escalation policies are included in the Business plans.

How a policy runs

1. The incident opens and the trigger's notification roles send the first notification.
2. Step 1 waits for its delay, counted from that first notification.
3. Each later step waits for its own delay, counted from the previous step.
4. After the last step, the policy starts over if it is set to repeat. Otherwise it is finished.

For example:

What stops it

Steps and targets

A policy has a name, an optional description and 1 to 10 steps. Each step has:

• A delay from 0 to 1440 minutes (24 hours).
• Targets, at least one per step:
  • Notification roles, which reach the role's people, custom recipients and integrations such as Slack.
  • People or on-call schedules per channel: email, SMS, phone call or push notification. A schedule means whoever is on call when the step is sent.

Each list holds up to 20 entries. SMS and phone calls use your credits.

Deleting a role, a person or a schedule removes it from every step. That can leave a step with no targets, so review your policies after removing someone from the team.

Repeat

After the last step, a policy can start over:

• Repeat times: 0 to 10. 0 means it doesn't repeat.
• Repeat after: 1 to 1440 minutes between rounds. Required when it repeats.

Attach a policy

You can attach a policy at three levels. The most specific one wins:

1. Trigger: the policy set on the trigger itself.
2. Server: used by the server's triggers that have no policy of their own.
3. Group: used when neither the trigger nor the server has one. Subgroups without their own policy inherit it.

Each trigger, server and group can have one policy. Clearing a policy at one level lets the next one apply. Deleting a policy removes it from everything that used it, which then relies on notification roles only.

Test a policy

A dry run shows who each step would reach right now, resolving roles and schedules as of this moment. Nothing is sent. Run it after changing a rotation or a role, since the answer can change as shifts change.

Who can manage policies

Everyone on the account can see policies and run a dry run. Creating, editing and deleting them needs the on-call permission. Attaching a policy to a server or group needs write access to it.

Relation to repeat notifications

Use a role repeat to keep reminding the same people. Use a policy when the alert should move on to someone else.

API

Authenticate with an API key.

On a trigger, send escalation_policy_id inside the trigger's data, next to notification_roles. Use null to clear it. Leaving it out of an update keeps the current policy.

A policy looks like this:

{
  "name": "Primary",
  "description": "On-call first, then the team lead",
  "repeat_times": 2,
  "repeat_after_minutes": 30,
  "steps": [
    {
      "delay_minutes": 5,
      "targets": {
        "recipients": {
          "sms": {"schedules": [12]},
          "notification": {"schedules": [12]}
        }
      }
    },
    {
      "delay_minutes": 15,
      "targets": {
        "notification_roles": [41],
        "recipients": {
          "call": {"contacts": [7]}
        }
      }
    }
  ]
}

Under recipients, the channels are email, sms, call and notification (push). Each takes clients (the account owner), contacts (team members) and schedules.