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

# Integrations

> Connect notification channels for your automation rules

Integrations define **where** notifications are sent when an automation rule fires. They are scoped to your **organization** and can be reused across multiple rules and projects.

Mirador supports three integration types:

| Type        | Description                             |
| ----------- | --------------------------------------- |
| **Webhook** | Send an HTTP POST to any URL            |
| **Slack**   | Post a message to a Slack channel       |
| **Email**   | Send an email to one or more recipients |

## Adding an Integration

You can create integrations in two ways:

* From the **rule creation form** — click the **Add Integration** button in the integrations section
* From the **integrations list** — click the **Create Integration** button

Both open the same creation dialog.

### Webhook

Webhook integrations send an HTTP POST request with rule match data to the URL you provide.

<Steps>
  <Step title="Select Webhook type">
    Choose **Webhook** as the integration type.
  </Step>

  <Step title="Enter a name">
    Give the integration a descriptive name (e.g., "PagerDuty Alerts" or "Internal Monitoring").
  </Step>

  <Step title="Enter the URL">
    Provide the HTTP endpoint that will receive the POST request.
  </Step>

  <Step title="Add custom headers (optional)">
    Add any headers your endpoint requires — for example, an `Authorization` header or a custom `X-API-Key`. Click **Add Header** for each key-value pair.
  </Step>

  <Step title="Save">
    Click **Save** to create the integration.
  </Step>
</Steps>

#### Webhook payload

When a rule fires, Mirador sends an HTTP `POST` with a JSON body describing the match. Use it to feed any system that accepts HTTP webhooks — incident management tools, logging pipelines, or custom dashboards.

```json theme={null}
{
  "schema_version": "1.0",
  "event_id": "5e2a9c14-7b3d-4f88-9a1e-6c0b2d4f8a31",
  "event_timestamp": "2026-06-18T16:12:34Z",
  "rule_id": "b7c4e90a-1f22-4d6b-8e33-9a0f1c2d3e44",
  "rule_name": "Failed Bridge Transfers",
  "match_reason": "trace.attributes[\"status\"] == \"failed\" && \"bridge\" in trace.tags",
  "project_name": "Production",
  "entities": [
    { "type": "trace", "id": "4bf92f3577b34da6a3ce929d0e0e4736" }
  ]
}
```

| Field             | Description                                                           |
| ----------------- | --------------------------------------------------------------------- |
| `schema_version`  | Version of the webhook payload schema. Bumped when the shape changes. |
| `event_id`        | Unique id for this delivery. Use it to dedupe retried webhooks.       |
| `event_timestamp` | When the rule match occurred, as an ISO 8601 UTC timestamp.           |
| `rule_id`         | ID of the rule that matched                                           |
| `rule_name`       | Human-readable name of the rule                                       |
| `match_reason`    | The condition that triggered the match                                |
| `project_name`    | Project the matched entity belongs to                                 |
| `entities`        | The entities that matched the rule (see below)                        |

Each item in `entities` identifies one matched object:

| Field  | Description                                                                       |
| ------ | --------------------------------------------------------------------------------- |
| `type` | The kind of entity. Today this is always `"trace"`.                               |
| `id`   | The entity's id. For a `trace`, fetch the full record with `GET /v1/traces/{id}`. |

The payload identifies *what* matched, not the trace's contents — read each entity's `id` and fetch the full record from the [REST API](/api/overview).

<Note>
  `entities` is intentionally a typed list. Today every match produces a `trace`
  entity, but other entity types (for example, `fx`) may be delivered through the
  same array in the future. Branch on `type` rather than assuming `entities[0]` is
  a trace, so your consumer keeps working as new types are added.
</Note>

<Tip>
  See [Exporting traces](/api/trace-export) for an end-to-end recipe that consumes
  this payload and opens a ticket with the full trace attached.
</Tip>

### Slack

Slack integrations post messages directly to a channel in your workspace.

<Steps>
  <Step title="Select Slack type">
    Choose **Slack** as the integration type.
  </Step>

  <Step title="Enter a name">
    Give the integration a descriptive name (e.g., "Alerts — #ops-alerts").
  </Step>

  <Step title="Connect your Slack workspace">
    Click **Connect Slack**. A popup will open asking you to authorize Mirador in your Slack workspace. Approve the connection.
  </Step>

  <Step title="Select a channel">
    After authorization, a dropdown appears listing your Slack channels. Select the channel where you want notifications posted.
  </Step>

  <Step title="Save">
    Click **Save** to create the integration.
  </Step>
</Steps>

<Note>
  The Slack OAuth connection is per-organization. Once connected, any team member can create Slack integrations using the authorized workspace. You only need to authorize once.
</Note>

### Email

Email integrations send notifications to a list of recipients.

<Steps>
  <Step title="Select Email type">
    Choose **Email** as the integration type.
  </Step>

  <Step title="Enter a name">
    Give the integration a descriptive name (e.g., "On-call Team Emails").
  </Step>

  <Step title="Add recipients">
    Enter one or more email addresses. Click **Add Recipient** to add additional addresses.
  </Step>

  <Step title="Save">
    Click **Save** to create the integration.
  </Step>
</Steps>

## Managing Integrations

### Enable / Disable

Toggle an integration on or off without deleting it. Disabled integrations will not receive notifications even if linked to active rules.

### Editing

Click the **edit** button on any integration to update its name, URL, channel, recipients, or headers.

### Deleting

Click the **delete** button to remove an integration. You'll be asked to confirm before deletion.

<Info>
  You cannot delete an integration that is currently linked to one or more rules. Unlink it from all rules first, then delete.
</Info>

## Next Steps

<CardGroup cols={2}>
  <Card title="Rules" icon="filter" href="/automations/rules">
    Create rules that use your integrations
  </Card>

  <Card title="Activity" icon="bell" href="/automations/activity">
    See when your integrations fire
  </Card>
</CardGroup>