Skip to main content
Cortex connects to many third-party vendors whose system interfaces frequently change. As a result, integration behavior or configuration steps may shift without notice. If you encounter unexpected issues, check with your system administrator or refer to the vendor’s documentation for the most current information. Additionally, integration sync times vary and are subject to scheduling overrides and timing variance.
This article explains how to configure the integration for incident.io. For instructions on connecting incident.io to entities, see Connecting entities to incident.io. For information on how to use the integration, see Using the integration for incident.io.

Why use the integration for incident.io

incident.io is an incident management platform that coordinates how teams declare, respond to, and resolve incidents. The integration brings that data into Cortex, so an entity’s incident history and current on-call coverage sit alongside its ownership, dependencies, and Scorecard results. The integration for incident.io brings the following into Cortex:
  • Incidents - Active and historical incidents for an entity, with severity, status, and affected entities.
  • On-call schedules - Who’s on call now and who’s on call next for an entity. Requires the On-call category.
You can also build Scorecard rules and Cortex Query Language (CQL) queries against incident and on-call data, and track incident frequency and mean time to resolution (MTTR) in Eng Intelligence.

Using Cortex as a source of truth in incident.io

incident.io natively supports pulling Cortex teams and catalog entities into incident.io, so Cortex can serve as the source of truth for team and service data across both platforms. This is configured from the incident.io side. See incident.io’s Cortex integration docs for setup instructions.

Configuring incident.io

Prerequisites

  1. Users with the Configure Integrations permission can configure incident.io.
  2. Create an incident.io API key with the following scopes:
    • Create incidents
    • View all incident data, including private incidents
    • View data like public incidents and organization settings
    • View catalog types and entries
    • schedules.view
    • catalog_entries.view

Installing incident.io in Cortex

  1. From the main sidebar, expand Integrations, then select Configurations.
  2. Locate incident.io, then click Install. The incident.io side panel opens.
  3. In the incident.io side panel, do the following:
    1. From the Category dropdown, select the types of data to import (required):
      • Incidents - Imports incidents with severity, status, and affected entities.
      • On-call - Imports on-call schedules, including who’s on call now and next.
      For more information, see Integration categories.
    2. Under Configuration alias, enter the alias you’ll use to tie entity registrations to different configuration accounts (required).
    3. Under API key, enter your incident.io API key (required).
  4. Click Test connection. A successful connection means your integration is configured correctly.
  5. Click Save.
To modify an existing configuration, see Modifying an integration configuration.

Using multiple incident.io configurations

The incident.io integration supports multiple configurations. To add another:
  1. From the main sidebar, expand Integrations, then select Configurations.
  2. Locate incident.io, then click Settings.
  3. In the upper-right corner of the page, click Add configuration.
  4. Follow the steps in Installing incident.io in Cortex above.
Each configuration requires an alias, which ties entity registrations to a specific account. If no alias is specified, Cortex uses the default configuration. To set a default:
  1. From the main sidebar, expand Integrations, then select Configurations.
  2. Locate incident.io, then click Settings.
  3. Click the pencil icon next to a configuration.
  4. Toggle on Set as default. If you only have one configuration, it’s automatically set as the default.

Setting up a webhook for incident.io (Private Beta)

By default, Cortex pulls data from incident.io on a recurring sync. Adding a webhook is optional but recommended: it lets incident.io notify Cortex when an incident or on-call schedule changes, so updates appear in Cortex right away instead of on the next sync. A webhook belongs to a single incident.io configuration. If you have multiple configurations, set up a webhook for each one. You need the Configure Integrations permission in Cortex, and permission to manage webhooks in incident.io.
  1. Get the webhook URL from Cortex:
    1. From the main sidebar, expand Integrations, then select Configurations.
    2. Locate incident.io, then click Settings.
    3. Click the pencil icon next to a configuration.
    4. Under Webhook, click Set up webhook.
    5. Copy the Webhook URL. Leave this panel open; you’ll come back to it to save the secret.
  2. Create the webhook endpoint in incident.io:
    1. In incident.io, go to Settings > Webhooks and add a new endpoint.
    2. Paste the webhook URL from Cortex as the endpoint URL.
    3. Subscribe the endpoint to all events. Cortex acts on incident and schedule events and ignores the rest, so subscribing to everything means you won’t need to revisit the endpoint as Cortex adds support for more event types.
    4. Save the endpoint, then copy the Signing secret from the endpoint’s settings. The secret starts with whsec_.
  3. Save the secret in Cortex:
    1. Back in the Cortex side panel, paste the signing secret under Secret.
    2. Click Save secret. The webhook’s status changes from Awaiting secret to Active.
Cortex uses the secret to verify that each delivery came from incident.io, and rejects deliveries until a secret is saved. To confirm the webhook is working, update an incident in incident.io and check that the change shows up in Cortex within a few seconds.
Cortex continues to run its regular sync after a webhook is set up, so data stays complete even if a delivery is missed.

Rotating the webhook secret

Rotate the secret in incident.io first, then update it in Cortex:
  1. In incident.io, go to Settings > Webhooks, open the endpoint, and rotate its Signing secret. Copy the new secret.
  2. In Cortex, open the incident.io configuration and, under Webhook, click Rotate secret.
  3. Paste the new secret under New secret, then click Save new secret.
Cortex keeps accepting the previous secret for 24 hours after you save the new one, so no deliveries are lost during the rotation.

Deleting the webhook

  1. In Cortex, open the incident.io configuration and, under Webhook, click Delete webhook.
  2. In incident.io, delete the endpoint so it stops sending deliveries.
Once a webhook is deleted, Cortex stops accepting deliveries to its URL, and that URL can’t be reused. Setting up a webhook again issues a new URL, which you’ll need to add to incident.io as a new endpoint. Cortex continues to sync incident.io data on its regular schedule.
Last modified on November 16, 2026