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

# Grafana alerts

> Route Grafana Alerting notifications to Obsy via webhook contact point.

## Get your Obsy webhook URL

Your per-org Grafana webhook URL is:

```
https://api.obsy.ai/api/v1/webhooks/{orgId}/grafana
```

Find your `{orgId}` in **Settings → Organization** or from the **Create Monitors** modal in OTel Collector.

## Add Obsy as a contact point

1. In Grafana, go to **Alerting → Contact points**.
2. Click **Add contact point**.
3. Set **Name** to `Obsy`.
4. Under **Integration**, choose **Webhook**.
5. Set **URL** to your Obsy webhook URL.
6. Leave method as **POST** and content type as `application/json`.
7. Click **Test** — Grafana sends a test payload. Check **Alerts** in Obsy to confirm it arrived.
8. Click **Save contact point**.

## Add Obsy to a notification policy

1. Go to **Alerting → Notification policies**.
2. Either edit the **Default policy** or add a new nested policy.
3. Set the **Contact point** to `Obsy`.
4. Optionally add label matchers to route only specific alerts.

## Alert payload format

Obsy accepts the standard **Grafana AlertManager** webhook format. Each POST can contain multiple alerts in a single group. Obsy creates one Alert entity per item in the `alerts` array.

Key fields mapped:

| Grafana field                                  | Obsy field                         |
| ---------------------------------------------- | ---------------------------------- |
| `commonLabels.alertname` or `labels.alertname` | Alert name                         |
| `commonAnnotations.description`                | Description                        |
| `status`                                       | Status (firing / resolved)         |
| `labels.severity`                              | Severity (critical, warning, info) |
| `labels.service` or `labels.app`               | Service name                       |
| `labels.environment` or `labels.env`           | Environment                        |
| `alerts[].fingerprint`                         | `annotations.grafana_fingerprint`  |
| `alerts[].generatorURL`                        | `annotations.generator_url`        |

## Using labels for routing

Obsy infers service and environment from Grafana labels. Set these on your alert rules for best results:

```yaml theme={null}
labels:
  service: payment-service
  environment: production
  severity: critical
```

## Troubleshooting

<AccordionGroup>
  <Accordion title="Test payload arrives but real alerts don't">
    Check your notification policy — the policy must match the labels on your alert rules. Use Grafana's **Contact point testing** section to send a real alert through.
  </Accordion>

  <Accordion title="Service name shows as empty">
    Add a `service` or `app` label to your Grafana alert rule. Without this label, Obsy stores the alert without a service association.
  </Accordion>
</AccordionGroup>