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.
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.
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
- Users with the
Configure Integrationspermission can configure incident.io. - Create an incident.io API key with the following scopes:
Create incidentsView all incident data, including private incidentsView data like public incidents and organization settingsView catalog types and entriesschedules.viewcatalog_entries.view
Installing incident.io in Cortex
- From the main sidebar, expand Integrations, then select Configurations.
- Locate incident.io, then click Install. The incident.io side panel opens.
- In the incident.io side panel, do the following:
-
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.
- Under Configuration alias, enter the alias you’ll use to tie entity registrations to different configuration accounts (required).
- Under API key, enter your incident.io API key (required).
-
From the Category dropdown, select the types of data to import (required):
- Click Test connection. A successful connection means your integration is configured correctly.
- 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:- From the main sidebar, expand Integrations, then select Configurations.
- Locate incident.io, then click Settings.
- In the upper-right corner of the page, click Add configuration.
- Follow the steps in Installing incident.io in Cortex above.
- From the main sidebar, expand Integrations, then select Configurations.
- Locate incident.io, then click Settings.
- Click the pencil icon next to a configuration.
- 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 theConfigure Integrations permission in Cortex, and permission to manage webhooks in incident.io.
- Get the webhook URL from Cortex:
- From the main sidebar, expand Integrations, then select Configurations.
- Locate incident.io, then click Settings.
- Click the pencil icon next to a configuration.
- Under Webhook, click Set up webhook.
- Copy the Webhook URL. Leave this panel open; you’ll come back to it to save the secret.
- Create the webhook endpoint in incident.io:
- In incident.io, go to Settings > Webhooks and add a new endpoint.
- Paste the webhook URL from Cortex as the endpoint URL.
- 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.
- Save the endpoint, then copy the Signing secret from the endpoint’s settings. The secret starts with
whsec_.
- Save the secret in Cortex:
- Back in the Cortex side panel, paste the signing secret under Secret.
- Click Save secret. The webhook’s status changes from Awaiting secret to Active.
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:- In incident.io, go to Settings > Webhooks, open the endpoint, and rotate its Signing secret. Copy the new secret.
- In Cortex, open the incident.io configuration and, under Webhook, click Rotate secret.
- Paste the new secret under New secret, then click Save new secret.
Deleting the webhook
- In Cortex, open the incident.io configuration and, under Webhook, click Delete webhook.
- In incident.io, delete the endpoint so it stops sending deliveries.