# incident.io

> Connect incident.io so a declared incident joins the Ace incident already open for the same workload, and Ace reads updates, alerts, on-call and your service catalog during investigations.

Source: https://tryace.dev/docs/integrations/incident-io

Ace reads incident.io to see what your team declared, when impact started, which services were affected and who responded. Your service catalog, with owners and dependencies, appears on the System Map. Ace never writes to incident.io.

| | |
| --- | --- |
| Category | Paging |
| Ace reads | Declared incidents, updates and timeline, attached alerts, escalations, follow-ups, service catalog, on-call |
| Ace can change | Nothing (read-only) |
| Opens incidents | A declared incident joins the Ace incident already open for the same workload. It opens one if none is open. |
| Setup | Settings form |

## What Ace reads

- Incidents declared around the Ace incident, plus earlier ones still open or updated. Ace reads status, severity, type, lead, impact timestamps and custom fields.
- An incident's updates, timeline items and activity log.
- Attached alerts and their sources, linked incidents, escalations and follow-ups.
- Catalog services that match a name, ID or alias, with their owners.
- Who was on call in a schedule during the window.

Ace skips test and tutorial incidents. It doesn't use incident.io to verify a fix, because an incident closes when a person moves it on.

For the System Map, Ace discovers the services in your catalog with their owner teams, dependencies and tier, leaving out archived entries.

## What Ace can change

Nothing. Ace doesn't declare, update or close incidents, post updates, change your catalog or set anything up in incident.io.

## What opens an incident

A declared incident usually joins the Ace incident already open for the same workload, which your alert sources opened. If no incident is open, a live declared incident opens one.

Events arrive through a webhook endpoint you add, and Ace also polls incident.io every 2 minutes in case a delivery goes missing. Ace accepts **Public incident created (v2)**, **updated (v2)** and **status updated (v2)**, and ignores other events.

| incident.io status category | What Ace does |
| --- | --- |
| Triage, Live, Paused | Joins the Ace incident already open on the workload, or opens one. |
| Learning, Closed, Declined, Canceled, Merged | Marks the incident.io incident resolved in Ace. |

These only inform investigations:

- Test and tutorial incidents.
- Retrospective incidents, either by mode or because their impact ended before they were declared.
- Incidents whose type you list in **Not reliability incidents**, for example Security or Customer support.

Severity comes from the severity's name, for example Critical, Major, Minor, or SEV and P levels. If the name doesn't match, Ace uses the severity's rank.

A declared incident reaches an Ace incident only when a workload routes incident.io. In the workload's settings, under **Investigation triggers**, turn on **Integration alerts** and check incident.io under **Alert sources**. Routing incident.io alone doesn't narrow which sources Ace reads for that workload.

## Before you start

- The **admin** role in Ace. See [Roles and permissions](https://tryace.dev/docs/security/roles-and-permissions).
- Permission to create API keys and webhook endpoints in incident.io.

## Credentials and permissions

| Credential | Where to create it | Permissions | Why Ace needs it |
| --- | --- | --- | --- |
| API key (needed) | **Settings** > **API keys** | View data | Read incidents, updates and attached alerts, and poll for new incidents. |
| Same key (recommended) | Same | View catalog | Read your service catalog and show services on the System Map. |
| Same key (recommended) | Same | View on-call resources | Read on-call schedules. |
| Webhook signing secret (only for alerts) | **Settings** > **Webhooks**, on the endpoint's page | None | Verifies that deliveries come from incident.io. |

Without View catalog or View on-call resources, Ace still connects, but those reads report missing access and the System Map shows no incident.io services.

## Set up

### 1. Create the API key

1. Open **Settings** > **API keys** (`https://app.incident.io/settings/api-keys`) and choose **Add new**. Name it Ace.
2. Select **View data**, **View catalog** and **View on-call resources**.
3. Create the key and copy it, since incident.io shows it once.

### 2. Connect incident.io in Ace

1. Open **Settings** > **Data sources** and choose **incident.io**.
2. Fill in the form:
   - **API key**: the key you copied.
   - **Service catalog type** (optional): the catalog type that lists your services, by name or ID. When it's empty, Ace looks for one named Service.
   - **Not reliability incidents** (optional): incident types that inform investigations but never open an Ace incident, comma-separated.
3. Select **Connect incident.io**. Ace saves only if the key passes validation.

### 3. Add the webhook

1. Copy the webhook URL from the **Alerts** section.
2. In incident.io, open **Settings** > **Webhooks** and add an endpoint with the URL.
3. Subscribe to **Public incident created (v2)**, **updated (v2)** and **status updated (v2)**, then save.
4. Copy the signing secret from the endpoint's page.
5. In Ace, paste it into the signing secret field of the **Alerts** section and select **Save**.

Ace rejects deliveries that have a mismatched signature or are too old.

## Confirm it's working

- The connection shows **Connected** with your key's name once Ace reads its identity and lists incidents.
- The **Alerts** section shows **Waiting for first event** until the first signed delivery turns it **Verified**. Ace polls in the meantime.

## Disconnect

1. In Ace, open **Settings** > **Data sources** > **incident.io** and select **Disconnect**.
2. In incident.io, delete the webhook endpoint under **Settings** > **Webhooks**. Ace didn't create it, so Ace doesn't remove it.
3. Delete the API key under **Settings** > **API keys**.

## Next steps

- [How Ace works](https://tryace.dev/docs/concepts/how-ace-works)
- [PagerDuty](https://tryace.dev/docs/integrations/pagerduty)
- [All integrations](https://tryace.dev/docs/integrations)