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

# Rootly

> Connect ResolveAI with Rootly so Resolve can take pages first with Primary On-Call.

This guide explains how to connect ResolveAI with Rootly On-Call for [Primary On-Call](https://docs.resolve.ai/primary-on-call). Resolve is paged first on the escalation policies a team chooses, investigates, and either closes the alert or escalates it to the policy's existing responders.

## Prerequisites

* **A Rootly admin** who can create roles, API keys, and webhooks.
* **Admin access in Resolve**: an org admin, or a team admin for the team being set up.
* **A dedicated Rootly user for Resolve.** Create it in Rootly first. Resolve does not create it, and every team on the connection shares it.
* **A Global API key** with a custom On-Call role (see [Permissions](#permissions)).

## Permissions

In Rootly, the API key's On-Call role needs only the permissions below.

| Permission | Why Resolve needs it |
| - | - |
| **Alerts**: create, read, update | Read the page, then acknowledge, resolve, or escalate it and add a note with the decision. |
| **Escalation Policies**: create, read, update, delete | Add Resolve's path in front of each path on the chosen policies, keep it in position, and remove it when Resolve is taken off the pager. |
| **Alert Sources**: read | Identify where an alert came from. |
| **Services**: read, **Teams**: read | Match alerts to services and teams. |
| **Webhooks**: read | Check that the webhook is enabled and subscribed to the right events. |
| **On-Call Roles**: read (recommended) | Confirm the permissions above before the first page. |

Alerts: read, Teams: read, and Webhooks: read are enough for investigations. The rest are needed only to handle pages.

If write access to escalation policies is not an option, use manual setup. An admin makes the policy changes, and Resolve only verifies them.

## Set up Primary On-Call

Open Rootly on the **Integrations** page in Resolve and follow the guided setup.

**1. Create the role and the API key**

1. In Rootly, open **Settings** > **Roles & Permissions** > **On-Call** > **Create**, and turn on only the permissions listed above.
2. Open **Settings** > **API Keys** and create a Global API key. Choose that On-Call role. Any Incident Response role works.
3. Paste the key into Resolve and save. Resolve checks the key's permissions and lists any that are missing.

**2. Choose Resolve's Rootly user**

Select the dedicated Rootly user from the list.

**3. Create the webhook**

1. In Resolve, generate a webhook URL and copy it. The URL is shown only once.
2. In Rootly, open **Settings** > **Webhooks** and create a webhook with that URL. Enable it and subscribe to `alert.created` and `alert.updated`.
3. Copy the webhook's signing secret, then save the webhook. Rootly hides the secret after saving.
4. In Resolve, paste the signing secret and click **Save**.

Rootly has no test event for this webhook. Resolve checks that the webhook is enabled, subscribed to both events, and has a signing secret saved, and it verifies the signature on every delivery.

**4. Route pages to Resolve**

Choose the team's Rootly escalation policies, set an alert filter to **Handle pages**, and click **Review and apply**. See [Get started with Primary On-Call](https://docs.resolve.ai/primary-on-call-get-started.md).

> [tab] Resolve sets it up
>
> Resolve adds a path in front of each of the policy's paths, for the filter's conditions. Matching pages reach Resolve first. If Resolve does not respond within the fallback timeout, Rootly continues to that path's responders. Nothing else on the policy changes.
>
> Click **Confirm and enable Handle pages** to apply.

> [tab] Set it up myself
>
> Resolve lists the changes to make on each escalation policy, as steps for the Rootly UI or as API commands to run with a write-capable Rootly key that Resolve never receives. Use the exact names shown so Resolve can find the paths. Do not remove the policy's other paths.
>
> When the changes are made, click **Check Rootly**.

### Check health

On the **Integrations** page, open the Rootly connection. **Test Webhook Configuration** and **Test On-Call Paging Permissions** show whether the webhook and the API key are ready to handle pages.

## Labels for alert filters

A filter set to **Handle pages** can use only `rootly.payload.<field>` labels, which are fields of the alert payload Rootly receives. Common ones:

* `rootly.payload.alert_title`
* `rootly.payload.alert_priority`
* `rootly.payload.alert_urgency_id`
* `rootly.payload.severity`
* `rootly.payload.commonLabels.<name>`, for example `alertname`, `service`, `team`, `namespace`, or `cluster`

The Rootly service, team, and environment are not available as labels. The escalation policy is chosen in the policy picker, not in the filter.

## Fallback

Resolve's path copies the existing responders behind Resolve. If Resolve does not respond within the fallback timeout, Rootly pages the existing responders as usual.

## Terraform

Routing a filter changes each listed escalation policy, which other teams' pages may also use. If Terraform manages these policies, make the same change there so the next apply does not overwrite it. Manual setup shows the exact changes to make.

## Limitations

* Policies with deferral paths, quiet or conditional notifications, or a default path that is not last cannot be routed until they are changed in Rootly.
* If Resolve's paths are edited, reordered, or deleted in Rootly, Resolve reports that they no longer match and offers to restore them.

## Take Resolve off the pager

Change the alert filter from **Handle pages** to **Investigate** or **Off**, then click **Review and apply**. When no filter needs a policy any more, Resolve removes its paths and pages follow the policy as before. With manual setup, delete the paths Resolve lists and keep every other path.
