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

# Integrations and notification channels

> Connect Slack, Microsoft Teams, PagerDuty, Opsgenie or Email as aiAxonIQ notification channels: credentials, testing, how secrets are stored, and limits.

**Manage → Integrations** is where you connect the places aiAxonIQ sends
notifications. Each connection is a **notification channel**: a named
destination with its credential, which escalation policies page. A destination outlives any one rule, so it is managed
here rather than inside Alerts.

<Info>
  **Anyone in the organization can see which connections exist. Connecting,
  editing, testing and removing them requires the Admin role or higher.** A
  test sends a real message to a real channel, which is why it sits with Admin.
  Non-admins see the connection names and types, and *Details are admin-only*
  in place of the rest. See [Roles and permissions](/concepts/roles).
</Info>

## What you can connect

The Integrations page lists exactly **five** integrations. These are the only
channel types aiAxonIQ creates:

| Integration         | What connecting it does                                               | Credential                                                                                                                                                                      |
| :------------------ | :-------------------------------------------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| **Slack**           | Posts notifications into a Slack channel.                             | **Incoming webhook URL**, from the Slack app's Incoming Webhooks page. Must be `https` on `hooks.slack.com`. The Slack channel is chosen when you create the webhook, not here. |
| **Microsoft Teams** | Posts an Adaptive Card into a Teams channel.                          | **Incoming webhook URL**, from the channel's connector or a Workflows "post to a channel" trigger. Must be `https` on `webhook.office.com` or `logic.azure.com`.                |
| **PagerDuty**       | Raises a PagerDuty incident through the Events API v2.                | **Integration key** (routing key) from the PagerDuty service you want paged. Up to 128 characters.                                                                              |
| **Opsgenie**        | Creates an Opsgenie alert, routed through Opsgenie's own escalations. | **API key** from an API-type integration in Opsgenie — not a personal token. Up to 128 characters.                                                                              |
| **Email**           | Sends notifications to a fixed list of addresses.                     | **Recipients** — 1 to 20 addresses. No mail-server settings: delivery uses the platform's mail transport.                                                                       |

<Note>
  **The icons elsewhere in the product are not integrations.** aiAxonIQ
  recognises many technologies in your telemetry and shows their logos. Only
  the five above can be connected as a notification destination. Pulling data
  *out* of aiAxonIQ into Grafana or another Prometheus client is a different
  mechanism — see [Grafana and Prometheus clients](/guides/integrations/grafana).
</Note>

A webhook URL must not contain a username or password, and any other host is
refused. That is a security control, not a formatting rule: a destination URL
you choose is a request the platform makes on your behalf, and a genuine Slack
or Teams webhook is never anywhere else.

### Generic outbound webhooks are off

<Danger>
  **A generic webhook channel cannot be created.** Outbound webhooks to an
  arbitrary URL are turned off by default, pending server-side request-forgery
  protection, request signing and retry handling, and the Integrations page does
  not offer one.

  If your organization already has webhook channels from before this page
  existed, the page counts them under **Not shown here**. They cannot be edited
  here, and they **do not deliver** unless your operator has turned webhook
  delivery on for the whole deployment — a test of one reports
  `webhook_delivery_disabled`.
</Danger>

## How credentials are stored

Channel credentials are bearer secrets: whoever holds a Slack webhook URL or a
PagerDuty key can post as you. aiAxonIQ treats them that way.

* **Sealed before storage.** A credential is sealed with AES-GCM under a
  server-held key before it is written, and decrypted only at the moment a
  notification or test is sent. Keys can be rotated without downtime for your
  channels.
* **Never sent back to you.** The list of connections returns only each one's
  name and type, to every role. Admins additionally see a short, non-reversible
  summary — whether a webhook is set, a recipient count, the last four
  characters of a key — never the credential itself.
* **Not recoverable.** Once saved, a credential cannot be revealed. To change
  one, enter the new value; to move a connection elsewhere, remove it and add
  it again.
* **Audited.** Creating, editing, testing and removing a connection are
  recorded in the [Audit log](/guides/audit), with who did it and whether a test
  succeeded.

<Note>
  On a self-hosted deployment, channels created before credential sealing was
  introduced remain readable in their original form until your operator
  re-seals them with the rotation procedure. Every channel created or edited
  since is sealed.
</Note>

## Connect a channel

<Steps>
  <Step title="Get the credential from the provider">
    Create the incoming webhook (Slack, Teams), the Events API v2 integration
    (PagerDuty) or the API integration (Opsgenie) in that product first. For
    Email, decide the recipient list.
  </Step>

  <Step title="Open Integrations">
    Go to **Manage → Integrations** and choose the integration.
  </Step>

  <Step title="Fill in the dialog">
    Give the connection a **Name**. It is how the connection is shown in
    escalation policies — two Slack channels are told apart by this and nothing
    else — so name it after its destination, for example *#payments-oncall*.
    Then enter the credential.
  </Step>

  <Step title="Test before saving">
    Press **Test connection**. A `[TEST]` message is delivered with what you
    typed, and nothing is saved yet.
  </Step>

  <Step title="Connect">
    Press **Connect**. The connection appears on the integration's page, ready to
    be chosen by an escalation policy.
  </Step>
</Steps>

### Where connections are used

* **Escalation policies** page connections level by level. See
  [Escalation policies](/guides/alerts/escalation-policies).
* **SLO error-budget policies** can record a connection alongside their
  thresholds. Recording it does not by itself send anything: no notification is
  delivered to that connection when a threshold is crossed. See
  [Service level objectives](/guides/slos/overview).

<Note>
  **The alert rule form configures its channel directly.** When you create a
  rule under **Alerts**, you pick a channel type and enter its configuration on
  the rule itself, rather than choosing one of these connections. See the
  channel settings in [Alerting](/guides/alerts/overview).
</Note>

## Testing a saved connection

Every saved connection has **Send test**. It sends a `[TEST]` message and tells
you whether the provider accepted it and how long that took.

* A successful test means the provider **accepted** the message. Check the
  destination too — a provider can accept a message and still drop it.
* Tests use a separate deduplication key in PagerDuty and Opsgenie, so a test
  never merges with, or resolves, a real incident.
* Tests are **not** withheld by maintenance windows.

If the stored configuration cannot produce a delivery at all — a missing key,
for example — the connection shows **This connection cannot deliver**. That
warning is the only health signal the page has: the absence of a warning is not
a guarantee that the next message will arrive.

## Delivery behaviour

Notifications are recorded before they are attempted, then delivered
independently per channel — a Slack outage does not affect the PagerDuty page
for the same alert.

* Slack, Teams, PagerDuty and Opsgenie requests time out after 10 seconds and
  are attempted up to four times in quick succession (waits of 1, 5 and 30
  seconds). A `4xx` answer is not retried: a rejected payload will be rejected
  again.
* A delivery that still fails with a temporary error — including an email the
  mail server did not accept — is retried later, up to six attempts in total
  over roughly half an hour, then marked failed. Retrying longer would deliver
  an alert about something long resolved.
* By default each channel accepts at most **60 notifications per minute**
  per organization. Beyond that, notifications are withheld rather than queued;
  `CRITICAL` notifications are exempt.

## Removing a connection

**Remove** deletes the connection and its credential. It cannot be recovered.
Any SLO error-budget policy that recorded it is detached automatically, and the
response says how many.

<Warning>
  **Check escalation policies before you remove a connection.** A policy level
  that still names a removed connection fails as a whole — none of the level's
  channels is notified, not just the removed one. Edit every level that names a
  connection before removing it. See
  [Escalation policies](/guides/alerts/escalation-policies).
</Warning>

## Security considerations

* Keep connecting and testing with Admins. A test is a real message, and a lower
  bar would let anyone post into your incident channels.
* Treat a webhook URL as a password: rotate it at the provider if it has been
  shared, then edit the connection with the new URL.
* Prefer a dedicated PagerDuty service integration and an Opsgenie API
  integration for aiAxonIQ, so you can revoke aiAxonIQ's access at the provider
  without affecting anything else.
* Email recipients receive whatever the alert contains, including the rule name
  and runbook link; use team distribution lists rather than personal addresses.

## Verify it works

<Steps>
  <Step title="Send a test">
    On the connection, press **Send test**. Expect **Test delivered** with a
    latency in milliseconds, and a `[TEST]` message at the destination.
  </Step>

  <Step title="Check the audit log">
    An *integration channel tested* entry appears in the
    [Audit log](/guides/audit) with the outcome.
  </Step>

  <Step title="Exercise it for real">
    Put the connection on a one-level escalation policy and let an incident go
    unacknowledged — see [Escalation policies](/guides/alerts/escalation-policies).
  </Step>
</Steps>

## Troubleshooting

<AccordionGroup>
  <Accordion title="'webhookUrl must be hosted on …'">
    The URL is not on the provider's own webhook host. Copy the webhook URL
    exactly as Slack or Teams issued it. Custom domains and proxies are refused.
  </Accordion>

  <Accordion title="'webhookUrl must use https' or 'must not embed credentials'">
    Use the `https` URL the provider issued, without a `user:password@` part.
  </Accordion>

  <Accordion title="The test fails with a 4xx from the provider">
    The provider rejected the credential or the payload. Regenerate the webhook
    or key at the provider and edit the connection. `4xx` answers are not
    retried.
  </Accordion>

  <Accordion title="Email tests fail with 'No SMTP configured'">
    Email delivery depends on a mail transport configured for your deployment.
    On a self-hosted deployment your operator must configure one; until then,
    use another channel. Do not rely on email as your only channel either way.
  </Accordion>

  <Accordion title="The buttons are disabled">
    Managing integrations requires the Admin role. Ask an Admin or Owner.
  </Accordion>

  <Accordion title="Edit is disabled on an older connection">
    Connections created before this page existed may be stored in a form it
    cannot edit. Remove the connection and add it again — and update any
    escalation policy levels that named it.
  </Accordion>

  <Accordion title="I need a generic webhook">
    Not available: generic outbound webhooks are off by default. Use Slack,
    Teams, PagerDuty, Opsgenie or Email.
  </Accordion>
</AccordionGroup>

## Next

<CardGroup cols={2}>
  <Card title="Escalation policies" icon="route" href="/guides/alerts/escalation-policies">
    Page connections when nobody acknowledges.
  </Card>

  <Card title="Alerting" icon="bell" href="/guides/alerts/overview">
    Rules, conditions and the Test action.
  </Card>

  <Card title="Grafana and Prometheus clients" icon="chart-line" href="/guides/integrations/grafana">
    Query aiAxonIQ from Grafana.
  </Card>

  <Card title="Incidents" icon="fire" href="/guides/incidents/overview">
    What notifications are about.
  </Card>
</CardGroup>