> ## Documentation Index
> Fetch the complete documentation index at: https://docs.elementary-data.com/llms.txt
> Use this file to discover all available pages before exploring further.

# incident.io

Elementary's incident.io integration enables sending alerts to [incident.io](https://incident.io) when data issues are detected.

Alerts are sent as **alert events** to an incident.io [HTTP Alert Source](https://incident.io/docs/alerting/alert-sources). incident.io then creates or updates alerts based on your routing and escalation rules.

To send alerts to incident.io, you need to create [alert rules](https://docs.elementary-data.com/cloud/features/alerts-and-incidents/alert-rules.md) and select incident.io as the destination.

## Prerequisites

You need an incident.io account with access to create Alert Sources.

## Create an HTTP Alert Source in incident.io

Before connecting Elementary, you need to create an HTTP Alert Source in incident.io:

1. In incident.io, go to **Alerts** → **Configuration** → **Alert Sources**.
2. Click **Create alert source**, search for **HTTP**, and select it.

![Search for HTTP alert source in incident.io](https://mintcdn.com/elementary/sosCZrKqfTElIvQr/pics/cloud/incident_io_search_http_source.png?fit=max\&auto=format\&n=sosCZrKqfTElIvQr\&q=85\&s=14f063a5c12bcdeb994b27d45a2023b1)

3. Give the alert source a name (e.g. "Elementary Cloud"), select **Default** as the type, and click **Continue**.

![Create HTTP alert source with name and type](https://mintcdn.com/elementary/sosCZrKqfTElIvQr/pics/cloud/incident_io_create_http_source.png?fit=max\&auto=format\&n=sosCZrKqfTElIvQr\&q=85\&s=8ec08532a3462eb3d34604b88531bfdc)

4. On the connection details page, you will see the **URL** and **authentication headers**. You will need the **alert source config ID** (from the URL) and the **API token** (from the Authorization header) when connecting in Elementary. Keep this page open — you will come back to it after sending a test alert.

![HTTP alert source connection details](https://mintcdn.com/elementary/sosCZrKqfTElIvQr/pics/cloud/incident_io_http_source_details.png?fit=max\&auto=format\&n=sosCZrKqfTElIvQr\&q=85\&s=151180dcb3f3eda5cfb0c19f9273186b)

> [!NOTE]
>
> The API token is a secret. Keep it secure and do not share it publicly.

## Connect incident.io in Elementary

1. Go to the **Environments** page on the sidebar.

2. Select an environment and click connect on the **Connect incident management tool** card, and select **incident.io**.

![Select incident.io as incident management tool](https://mintcdn.com/elementary/sosCZrKqfTElIvQr/pics/cloud/incident_io_select_provider.png?fit=max\&auto=format\&n=sosCZrKqfTElIvQr\&q=85\&s=bfa3cabb21f3e5c81d10b1b3f81cf7a6)

3. Fill in the connection details from your incident.io alert source:
   * **Source name** — a display name for this alert source (e.g. "Elementary Cloud")
   * **Alert source config ID** — the config ID from the alert source URL
   * **API token** — the Bearer token from the authentication headers

![Enter incident.io connection details](https://mintcdn.com/elementary/sosCZrKqfTElIvQr/pics/cloud/incident_io_connect_form.png?fit=max\&auto=format\&n=sosCZrKqfTElIvQr\&q=85\&s=7c4e140826f92a2577697b22e022dfca)

4. Expand **Test connection** to send a test alert and verify the integration is working.

![Test the incident.io connection](https://mintcdn.com/elementary/sosCZrKqfTElIvQr/pics/cloud/incident_io_test_connection.png?fit=max\&auto=format\&n=sosCZrKqfTElIvQr\&q=85\&s=fa82d14d3c375f7e2434bda27d55e6e9)

> [!WARNING]
>
> The test connection sends a real alert event to incident.io. You may need to manually resolve or close it after testing.

5. Click **Save**. **incident.io** will now be available as a destination on the [alert rules](https://docs.elementary-data.com/cloud/features/alerts-and-incidents/alert-rules.md) page.

> [!TIP]
>
> You can add multiple alert sources by clicking **+ Add source** — for example, to route different alert rules to different incident.io alert sources.

## Configure the Alert Source in incident.io

After sending a test alert from Elementary, go back to the incident.io alert source setup page. You should see the test alert appear in the alerts list on the right side. Click **Continue**.

![Alert source showing received test alert with Continue button](https://mintcdn.com/elementary/sosCZrKqfTElIvQr/pics/cloud/incident_io_source_with_test_alert.png?fit=max\&auto=format\&n=sosCZrKqfTElIvQr\&q=85\&s=22e41e7989db336fa46d94975fe454b1)

2. You will land on the alert source configuration page, where you can set up:
   * **Title** — how the alert title is extracted from the payload
   * **Connections** — routing rules for how alerts create incidents
   * **Attributes** — map metadata fields from the alert payload to structured attributes (see below)
3. Click **Save** to finish the alert source setup.

## Configure Alert Attributes

Elementary sends metadata with each alert (such as severity, owners, and tags). To use these fields for routing, filtering, or displaying in incident.io, configure **Alert Attributes** in your alert source settings.

In the alert source configuration, click **Attributes** to map metadata fields. The alert payload is displayed on the right, making it easy to see which fields are available and map them.

![Configure alert attributes in incident.io](https://mintcdn.com/elementary/sosCZrKqfTElIvQr/pics/cloud/incident_io_attributes.png?fit=max\&auto=format\&n=sosCZrKqfTElIvQr\&q=85\&s=57b1b291d9e8fd04c06d1b5afe5d74c8)

### Available metadata fields

Elementary sends the following metadata fields depending on the alert type. All fields are optional — they are included only when the data is available.

| Field | Type | Description |
| - | - | - |
| `metadata.severity` | String | Alert severity (e.g. `warn`, `fail`, `error`) |
| `metadata.owners` | Array of strings | Asset and test owners (email addresses) |
| `metadata.tags` | Array of strings | Asset and test tags |
| `metadata.environment` | String | Elementary environment name |
| `metadata.test_description` | String | Test description (test alerts only) |
| `metadata.source` | String | Pipeline tool name (pipeline alerts only) |
| `metadata.connector` | String | Connector name (pipeline alerts only) |
| `metadata.failure_reason` | String | Failure reason (pipeline alerts only) |

> [!TIP]
>
> When configuring attributes, use the test alert payload as a reference — it includes sample values for the common metadata fields, making it easy to set up mappings.

### Recommended attribute mappings

We recommend mapping these fields in incident.io:

* **`metadata.severity`** → a **Severity** or text attribute — enables routing alerts by severity
* **`metadata.owners`** → a multi-value text attribute — enables filtering and routing by data owner
* **`metadata.tags`** → a multi-value text attribute — enables filtering by tag

> [!NOTE]
>
> For array fields like `owners` and `tags`, make sure to select a type that supports multiple values in incident.io's attribute configuration.

If you need additional metadata fields for your routing that are not currently included, [reach out to us](https://www.elementary-data.com/contact-us) and we'll work with you to add them.

## How alerts work

### Alert creation and deduplication

Each Elementary alert includes a **deduplication key** based on the alert's identity (test, model, or pipeline). incident.io uses this key to:

* **Create** a new alert when a new issue is detected
* **Deduplicate** — avoid creating duplicate alerts for the same ongoing issue
* **Auto-resolve** — when a test passes again, Elementary sends a resolved event with the same deduplication key, which closes the alert in incident.io

### Alert types

Elementary sends the following alert types to incident.io:

* **Test alerts** — dbt and Elementary test failures
* **Model alerts** — dbt model and snapshot failures
* **Source freshness alerts** — source freshness check failures
* **Pipeline alerts** — pipeline connector failures (Fivetran, etc.)
* **Resolved alerts** — automatically sent when a previously failing test/model passes

### Link to Elementary

Each alert includes a **source URL** linking back to the relevant page in Elementary Cloud, so you can quickly investigate the issue.

### Alerts and incidents in incident.io

Each alert sent by Elementary appears in incident.io with full metadata, attributes, and a link back to Elementary Cloud.

![Elementary alert detail in incident.io](https://mintcdn.com/elementary/sosCZrKqfTElIvQr/pics/cloud/incident_io_alert_detail.png?fit=max\&auto=format\&n=sosCZrKqfTElIvQr\&q=85\&s=88f81f86c8fd3a97a134ec56bff55a89)

Alert detail in incident.io

When an alert matches your incident.io routing rules, it automatically creates an incident with full context.

![Incident created from Elementary alert in incident.io](https://mintcdn.com/elementary/sosCZrKqfTElIvQr/pics/cloud/incident_io_incident.png?fit=max\&auto=format\&n=sosCZrKqfTElIvQr\&q=85\&s=10d864033e13cd4ec3f43af07ad2eea3)

Incident created from an Elementary alert

### Slack notifications

If you have Slack notifications configured in incident.io, alerts and incidents will appear in your Slack channels with the alert details, labels, and action buttons.

![Elementary alert notification in Slack via incident.io](https://mintcdn.com/elementary/sosCZrKqfTElIvQr/pics/cloud/incident_io_slack_notification.png?fit=max\&auto=format\&n=sosCZrKqfTElIvQr\&q=85\&s=756c4856d3c939457f4090def046e650)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.