Skip to main content
This guide explains how to connect ResolveAI with incident.io for Primary On-Call. Resolve is paged first on the alert routes a team chooses, investigates, and either closes the escalation or escalates it to the team’s existing escalation path.

Prerequisites

  • An incident.io admin who can create API keys and webhooks.
  • Admin access in Resolve: an org admin, or a team admin for the team being set up.
  • An enabled alert route that already pages a human escalation path. Resolve is placed in front of that path.
  • A way for incident.io to reach Resolve, shared by every team on the connection. Choose one:
    • A Resolve user: a dedicated incident.io user. It may need a paid seat.
    • A Slack or MS Teams channel: a dedicated channel with the incident.io app added to it. Do not reuse an active alert channel, so that people do not acknowledge Resolve’s pages by mistake.

Permissions

Resolve needs an incident.io API key with two permissions and no others.

Set up Primary On-Call

Open incident.io on the Integrations page in Resolve and follow the guided setup.
1

Create the API key

  1. In incident.io, go to Settings > API keys > Add new. Name it, for example, Resolve.
  2. Grant Create and manage on-call resources and Create and manage escalations.
  3. Copy the key before closing the dialog. incident.io shows it only once.
  4. Paste the key into Resolve and save. Resolve checks that the key can act on escalations.
2

Choose how incident.io reaches Resolve

Select A Resolve user or A Slack or Teams channel.For a channel, create a dedicated channel, add the incident.io app to it (/invite @incident.io in Slack), and enter the channel ID, not the channel name.
3

Create the webhook

  1. In incident.io, go to Settings > Webhooks and create an outgoing webhook with the URL Resolve shows.
  2. Subscribe to public_escalation.escalation_created_v1 and public_escalation.escalation_status_updated_v1.
  3. Copy the signing secret (it starts with whsec_) and paste it into Resolve. The secret is required: Resolve uses it to verify every delivery.
4

Send a test event

In incident.io, go to Settings > Webhooks, open the endpoint, go to Testing, and choose Send Example. Then run the check again in Resolve.
Resolve reports that it received a signed event from incident.io, with the time.
5

Route pages to Resolve

Set an alert filter to Handle pages and click Review and apply. See Get started with Primary On-Call. Then, in the review:
  1. Set the fallback timeout: how long incident.io waits for Resolve before it continues to the existing escalation path. Choose a value the team is comfortable with if Resolve is not able to respond in time.
  2. Click Choose escalation paths and select the existing escalation paths each filter routes on. Resolve creates a Resolve first path for each path selected.
  3. Click Apply changes.
Nothing changes in incident.io until Apply changes is clicked. Then Resolve:
  • Creates an escalation path named Resolve first followed by the name of each selected path. It pages Resolve, and continues to the existing path if Resolve does not respond within the fallback timeout. The existing path is not edited.
  • Switches the selected alert routes to the new path, or adds a rule that sends only the matching alerts to it.

Check health

On the Integrations page, open the incident.io connection. Event delivery shows when the last signed event arrived, and Test On-Call Setup Permissions shows whether the API key has both permissions.

Labels for alert filters

A filter set to Handle pages can use what incident.io sends with the alert:
  • The alert title
  • The alert source
  • priority
  • Any alert attribute with a single text or catalog value, by its name in snake case (for example, an attribute called Affected Service is affected_service)
  • The escalation path
Deduplication keys, labels from the source alert, and attributes with several values cannot be used to route pages.

Fallback

Keep the existing escalation path as it is. If Resolve does not respond in time, the acknowledgement timeout on Resolve’s level expires and incident.io continues to the existing path as usual. Resolve sets the timeout when it creates the path. To change the fallback timeout later, also set the acknowledgement timeout of Resolve’s level in incident.io to the new value, then apply again.

Limitations

  • Alert routes that choose their escalation path by expression must be switched by hand in incident.io.
  • Escalations with no related alert, such as ones created by hand, are not handled.
  • If routes or escalation paths are managed as code, make the same changes there so the next apply does not overwrite them.

Take Resolve off the pager

Change the alert filter from Handle pages to Investigate or Off, then click Review and apply. Resolve switches the alert routes back to the existing escalation path. The Resolve first path stays in incident.io, unused, and can be deleted there.