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
- In Rootly, open Settings > Roles & Permissions > On-Call > Create, and turn on only the permissions listed above.
- Open Settings > API Keys and create a Global API key. Choose that On-Call role. Any Incident Response role works.
- 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
- In Resolve, generate a webhook URL and copy it. The URL is shown only once.
- In Rootly, open Settings > Webhooks and create a webhook with that URL. Enable it and subscribe to
alert.createdandalert.updated. - Copy the webhook’s signing secret, then save the webhook. Rootly hides the secret after saving.
- In Resolve, paste the signing secret and click Save.
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 sets it up
- Set it up myself
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 onlyrootly.payload.<field> labels, which are fields of the alert payload Rootly receives. Common ones:
rootly.payload.alert_titlerootly.payload.alert_priorityrootly.payload.alert_urgency_idrootly.payload.severityrootly.payload.commonLabels.<name>, for examplealertname,service,team,namespace, orcluster
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.

