grafana-webhooks

Grafana Webhooks

Covers the Grafana Alerting webhook contact point (Grafana-managed alerting, the only alerting system in Grafana 11+; also Grafana Cloud).

Not covered: Grafana legacy dashboard alerting webhooks (removed in Grafana 11 — different payload with ruleName/evalMatches, no HMAC); Grafana OnCall / IRM outgoing webhooks (separate product, own templates and auth); Prometheus Alertmanager webhook_config (payload is a close relative — Grafana's is Alertmanager's plus extra fields — but Alertmanager has no HMAC signing).

When to Use This Skill

• How do I receive Grafana alert webhooks?
• How do I verify a Grafana webhook signature?
• What is X-Grafana-Alerting-Signature and how do I check it?
• Why is my Grafana webhook HMAC verification failing?
• How do I tell a firing alert from a resolved one in the Grafana payload?
• How do I secure a Grafana webhook contact point (HMAC, basic auth, bearer token)?

Verification (core)

HMAC-SHA256, lowercase hex, over the raw body — or over <unix-seconds> + ":" + rawBody when a timestamp header is configured. The digest is bare: no sha256= prefix, no t=...,v1= structure. Both header names are user-configurable; the signature header defaults to X-Grafana-Alerting-Signature and the timestamp header has no default name (unset = body-only signing).

Node:

const crypto = require('crypto');

function verify(rawBody, signature, timestamp, secret) {
  if (!signature || !secret) return false;
  const hmac = crypto.createHmac('sha256', secret);       // secret used as-is (UTF-8)
  if (timestamp) hmac.update(`${timestamp}:`);            // COLON separator, seconds
  hmac.update(rawBody);                                   // RAW bytes, never re-serialized JSON
  const expected = hmac.digest('hex');
  const received = Buffer.from(signature.toLowerCase(), 'utf8');
  const want = Buffer.from(expected, 'utf8');
  return received.length === want.length && crypto.timingSafeEqual(received, want);
}