> ## 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.

# incident.io

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

This guide explains how to connect ResolveAI with incident.io for [Primary On-Call](https://docs.resolve.ai/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.

| Permission | Why Resolve needs it |
| - | - |
| **Create and manage on-call resources** | Post decision notes, acknowledge or cancel escalations, create the escalation path that pages Resolve first, and switch alert routes to it. |
| **Create and manage escalations** | Escalate a page to the team's existing escalation path. |

## 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.

> [!TIP]
>
> 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](https://docs.resolve.ai/primary-on-call-get-started.md). 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.
