Grafana integration

Forward Grafana alerting notifications to Unit Oncall. Grafana's unified alerting sends a JSON body to a webhook contact point; Unit Oncall normalizes it, routes it to a Schedule, and pages the on-call responder.

Setup

1. In Unit Oncall, create a Webhook (Integrations → Webhooks → New). Choose a Team and default Schedule. Standard auth mode is the simpler choice — the secret is embedded in the URL, so no header setup is needed in the contact point — but Secure mode also works because Grafana webhook contact points can add a custom HTTP header. Copy the generated Webhook URL.
2. In Grafana, open Alerting → Contact points → Add contact point.
3. Choose Webhook as the integration type.
4. Set the URL to the Unit Oncall Webhook URL from step 1. Leave the HTTP method as POST.
5. Save, then attach the contact point to a notification policy so alerts are delivered to it.

Grafana's webhook payload contains a top-level status, a commonLabels object, and an alerts array. The recommended rule below reads the first alert in that array.

Webhook URL

Unit Oncall exposes a single unified receive endpoint. The token in the path identifies the webhook (and, in Standard mode, carries the secret):

POST https://<your-api-host>/api/v1/wh/{token}

• {token} is an opaque, encrypted value generated when you create the Webhook. Treat it as a credential.
• Standard auth mode (recommended for Grafana): the secret is embedded in the token, so the URL is self-contained.
• Secure auth mode: the secret is sent as the X-Webhook-Secret header or a webhook_secret body field. Grafana contact points can add custom HTTP headers, so Secure mode is also viable.

Recommended transformation rule

This rule reads the first entry of Grafana's alerts array. It uses the alertname label as the fingerprint, builds a title from the alert state and rule name, maps the Grafana severity label to Unit Oncall severities, and maps startsAt as the detection time.

{
  "name": "Grafana alerting",
  "description": "Maps Grafana unified alerting webhook payloads to Unit Oncall alerts.",
  "is_active": true,
  "mappings": {
    "fingerprint": {
      "type": "jsonpath",
      "path": "$.alerts[0].labels.alertname"
    },
    "title": {
      "type": "format",
      "format": "[{$.status}] {$.alerts[0].labels.alertname}"
    },
    "severity": {
      "type": "jsonpath",
      "path": "$.alerts[0].labels.severity",
      "mapping": {
        "critical": "critical",
        "warning": "warning",
        "info": "info"
      },
      "default": "warning"
    },
    "message": {
      "type": "jsonpath",
      "path": "$.alerts[0].annotations.summary",
      "default": "Grafana alert (no summary annotation provided)"
    },
    "timestamp": {
      "type": "jsonpath",
      "path": "$.alerts[0].startsAt"
    },
    "tags": {
      "type": "jsonpath",
      "path": "$.alerts[0].labels.team"
    }
  }
}

See the Transformation Rule reference for the full field and mapping syntax.

Troubleshooting

• No alert arrives. Use Grafana's Test action on the contact point, then confirm the Webhook is enabled in Unit Oncall and the URL is complete.
• 403 webhook disabled. The Webhook's is_enabled is false. Enable it.
• Fingerprint is empty. Your alert rule does not set an alertname label. Either add it, or point the fingerprint path at a label that is always present.
• Severity is always the default. The severity label was missing or had an unmapped value. Add a severity label to the rule, or extend the mapping table.
• Resolved alerts stay open. Grafana sends status: "resolved" with the same labels; make sure fingerprint resolves to the same value for firing and resolved notifications, and that startsAt is mapped so ordering is correct. See the note in the Transformation Rule reference.