Grafana

Navi.sh supports both the modern Grafana unified alerting format and the legacy single-alert format. Alerts with status: "resolved" automatically close the corresponding incident.

Endpoint: POST /api/v1/events/grafana/{token}

---

Setup in Grafana

1. In Grafana, go to Alerting → Contact points.
2. Click Add contact point.
3. Set Integration to Webhook.
4. Set the URL to your integration URL:

   https://api.navi.sh/api/v1/events/grafana/<token>

5. Leave HTTP Method as POST and Content-Type as application/json.
6. Click Test to send a test payload, then Save.
7. Assign the contact point to your Notification policies or individual alert rules.

---

Auto-resolve

Each alert in the alerts[] array is processed independently. Grafana sets status: "resolved" when an alert recovers — Navi.sh matches it to the open incident by fingerprint (or labels.alertname as fallback).

Make sure the Send resolved notifications option is enabled in your contact point settings.

---

Payload schema

Unified alerting format

Field	Type	Description
receiver	string	Contact point name.
status	string	Overall status: firing or resolved.
title	string	Top-level title (used if alerts[] is empty).
message	string	Top-level message (used if alerts[] is empty).
externalURL	string	Grafana instance URL.
groupKey	string	Group identifier.
groupLabels	object	Labels used for grouping.
commonLabels	object	Labels common to all alerts.
commonAnnotations	object	Annotations common to all alerts.
version	string	Payload version.
alerts	array	List of individual alert instances.

Per-alert fields

Field	Type	Description
status	string	firing or resolved.
labels	object	Alert labels. Include alertname and severity.
annotations	object	Include summary (title) and description.
fingerprint	string	Unique fingerprint for deduplication.
values	object	Current metric values (name → number).
startsAt	string (RFC3339)	Alert start time.
endsAt	string (RFC3339)	Alert end time.
generatorURL	string	Link to the Grafana alert expression.

---

Field mapping

Navi.sh incident field	Source
Title	annotations.summary → labels.alertname → top-level title → "Grafana Alert"
Description	annotations.description → annotations.message → top-level message
Severity	labels.severity
Dedup key	fingerprint → labels.alertname

---

Example payload

{
  "receiver": "navi-sh",
  "status": "firing",
  "groupKey": "alertname",
  "externalURL": "http://grafana:3000",
  "version": "1",
  "alerts": [
    {
      "status": "firing",
      "labels": {
        "alertname": "HighMemory",
        "severity": "warning"
      },
      "annotations": {
        "summary": "Memory usage above 85%",
        "description": "Pod memory is critically high"
      },
      "fingerprint": "xyz789abc",
      "startsAt": "2024-01-15T10:30:00Z",
      "endsAt": "0001-01-01T00:00:00Z",
      "values": { "memory_usage": 87.3 },
      "generatorURL": "http://grafana:3000/alerting/..."
    }
  ]
}

---

Legacy format

For older Grafana versions, a simple top-level payload is also supported:

{
  "title": "High Memory Usage",
  "message": "Memory usage exceeded the threshold on web-01",
  "state": "alerting"
}

---

Response

202 Accepted — all alerts in the batch were queued for processing.