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

# Grafana Alerting

> Connect Grafana Alerting to aciona.me with a webhook contact point.

## Overview

Grafana sends alerts to aciona.me through a **webhook contact point**. Each item in the payload's `alerts[]` becomes an alert in aciona.me, and resolved items automatically close the matching incident.

|                     |                       |
| ------------------- | --------------------- |
| **Source type**     | `Grafana`             |
| **Mechanism**       | Webhook contact point |
| **Correlation**     | Grafana `fingerprint` |
| **Auto-resolution** | ✅                     |

## Prerequisites

* Grafana with Grafana Alerting enabled and permission to create contact points.
* A service created in aciona.me and linked to a team with an active schedule.

## 1. Create the alert source in aciona.me

Under **Alert sources**, create a source of type **Grafana** — for example `Grafana - production`.

## 2. Copy the URL and the token

```bash theme={null}
POST https://ingress.aciona.me/webhooks/<alertSourceId>
X-Aciona-Token: <sourceToken>
```

<Warning>
  The token is shown only once. Copy it now.
</Warning>

## 3. Configure the contact point in Grafana

<Tabs>
  <Tab title="Through the UI">
    <Steps>
      <Step title="Alerting → Contact points → Add contact point">
        Name: `aciona-me`. Integration: **Webhook**.
      </Step>

      <Step title="URL">
        `https://ingress.aciona.me/webhooks/<alertSourceId>`
      </Step>

      <Step title="HTTP Method">
        `POST`
      </Step>

      <Step title="Authentication header">
        Add the `X-Aciona-Token` header with the source token. In versions that expose the field as *Authorization Header*, use `X-Aciona-Token` as the name and the token as the value.
      </Step>

      <Step title="Disable resolved message">
        Leave it **off**. This is the critical step of the integration.
      </Step>

      <Step title="Save and use the contact point">
        Point the notification policy (or the alert rules) at the `aciona-me` contact point.
      </Step>
    </Steps>
  </Tab>

  <Tab title="Through provisioning (YAML)">
    ```yaml contact-points.yaml theme={null}
    contactPoints:
      - orgId: 1
        name: aciona-me
        receivers:
          - uid: aciona-me-webhook
            type: webhook
            settings:
              url: https://ingress.aciona.me/webhooks/<alertSourceId>
              httpMethod: POST
              disableResolveMessage: false
            secureSettings:
              authorizationHeaderValue: '<sourceToken>'
    ```

    `disableResolveMessage: false` is the equivalent of Alertmanager's `send_resolved: true`.
  </Tab>
</Tabs>

## 4. Send a test alert

Use **Test** on the Grafana contact point, or force an alert rule to fire.

## 5. Confirm the incident

Under **Incidents**, the alert should appear within seconds, with the title from the Grafana alert and the severity translated from the `severity` label.

## 6. Set up automatic resolution

<Warning>
  **"Disable resolved message" must stay off**, both on the contact point and on the notification policy. With it on, Grafana does not send `resolved` items and aciona.me has no way to close the incident — it stays open indefinitely.
</Warning>

States normalized by aciona.me, item by item:

| `alerts[].status`              | Effect in aciona.me                            |
| ------------------------------ | ---------------------------------------------- |
| `firing`                       | Creates or aggregates an incident              |
| `alerting`                     | Creates or aggregates an incident              |
| `resolved`                     | Automatically resolves the correlated incident |
| `normal`                       | Automatically resolves the correlated incident |
| `paused`, `pending`, `no_data` | Ignored                                        |

Correlation uses Grafana's `fingerprint`, with fallbacks based on the rule identifier. That identifier must stay stable between the trigger and the recovery.

## Routing to the right service

Add a `service` label to your alert rules with the exact service name in aciona.me:

```yaml theme={null}
labels:
  service: payments-api
  severity: critical
```

## Troubleshooting

<AccordionGroup>
  <Accordion title="The incident opens but never closes" icon="triangle-alert">
    "Disable resolved message" is on somewhere — contact point or notification policy. Turn it off in both.
  </Accordion>

  <Accordion title="401 response in Grafana" icon="lock">
    The `X-Aciona-Token` header is missing or wrong. If the token was rotated, update the contact point.
  </Accordion>

  <Accordion title="The incident lands on the wrong service" icon="server">
    Add a `service` label to the alert rule with the exact service name in aciona.me. Without it, routing falls back to other hints in the payload.
  </Accordion>

  <Accordion title="Several incidents for the same problem" icon="copy">
    The `fingerprint` is changing between triggers — usually because the rule's labels change. Stabilize the labels that make up the alert's identity.
  </Accordion>
</AccordionGroup>

<Card title="More fixes" icon="life-buoy" horizontal href="/en/troubleshooting/overview" />