Skip to main content
This guide explains how to connect ResolveAI with Rootly On-Call for 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

In Rootly, the API key’s On-Call role needs only the permissions below. 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.
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.

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.