Grafana

Turn Grafana alerts into timeline sparklines on your Lock Screen. See metric history at a glance with real-time updates while alerts are firing.

How It Works

1. Webhook — Grafana fires an alert and sends the webhook to pushward-grafana
2. Query — The service queries Prometheus or VictoriaMetrics for the metric's recent history
3. Timeline — A Live Activity starts with a sparkline chart showing the metric over time
4. Poll — While the alert is firing, the service polls for new data points and pushes updates
5. Resolve — When the alert resolves, the activity ends with a final snapshot

Setup

1. Get Your Integration Key

Open the PushWard app → Settings → Integration Key to find your default hlk_ key.

To create a dedicated key for this integration:

1. Go to Settings → Manage Keys
2. Tap +
3. Set name (e.g. "Grafana"), choose , Full management scope, and restrict tografana-*
4. Copy the generated hlk_ key

2. Deploy the Service

services:
  pushward-grafana:
    image: ghcr.io/mac-lucky/pushward-grafana:latest
    ports:
      - "8090:8090"
    environment:
      PUSHWARD_URL: https://api.pushward.app
      PUSHWARD_API_KEY: hlk_YOUR_INTEGRATION_KEY
      PUSHWARD_METRICS_URL: http://prometheus:9090
      # Optional: webhook secret (must match Grafana contact point)
      # PUSHWARD_WEBHOOK_TOKEN: your-shared-secret
      # Optional: Grafana API for auto-extracting PromQL from alert rules
      # PUSHWARD_GRAFANA_URL: http://grafana:3000
      # PUSHWARD_GRAFANA_API_TOKEN: glsa_...
    restart: unless-stopped

3. Configure Grafana Contact Point

1. Navigate to Alerts & IRM > Alerting > Contact points
2. Click + Add contact point
3. Select Webhook as the integration type
4. Set URL to your pushward-grafana instance (e.g. http://pushward-grafana:8090/webhook)
5. If you set PUSHWARD_WEBHOOK_TOKEN, expand Optional settings and set Authorization header scheme to Bearer with the matching token
6. Click Test, then Save

Create a Notification policy that routes alerts to this contact point.

Configuration

Dashboard Links

The bridge forwards the alert's silenceURL, generatorURL, and panel links straight through to the notification — both http:// and https:// schemes are accepted, so a self-hosted Grafana on a LAN (e.g. http://grafana.internal/d/abc) round-trips cleanly for users on VPN. URLs without an http(s):// scheme are dropped on the way in.

PromQL Resolution

pushward-grafana needs a PromQL expression to query metric history. It resolves the query in this order:

1. Auto-extract (recommended) — If PUSHWARD_GRAFANA_URL and PUSHWARD_GRAFANA_API_TOKEN are set, the service reads the alert rule's PromQL expression via the Grafana API. No per-rule configuration needed.
2. Annotations — Add annotations to your Grafana alert rules to specify the query explicitly.
3. Webhook values — Falls back to the numeric values included in the Grafana webhook payload (no history, just the current value).

Per-Rule Annotations

Add these annotations to your Grafana alert rules when not using auto-extract:

Severity Colors

The sparkline accent color and icon are derived from the severity label on the alert rule: