# Verify Grafana webhooks

Grafana can sign each notification so you can confirm it came from your Grafana and wasn't changed on the way, but only once you set a secret in the contact point's HMAC Signature settings, on Grafana 12.0 or later. The `X-Grafana-Alerting-Signature` header, which you can rename, holds a hex HMAC-SHA256 of the raw body, or of a Unix timestamp, a colon and the body if you also name a timestamp header. Grafana's docs describe no SDK for this, so you compute it yourself.

These pages cover the Webhook integration on a Grafana Alerting contact point. Grafana IRM has its own [outgoing webhooks](https://grafana.com/docs/grafana-cloud/observe-and-act/respond-to-incidents/integrations/custom-integrations/outgoing-webhooks/), with separate templates and authentication.

Agent skill: `npx skills add hookdeck/webhook-skills --skill grafana-webhooks` ([details](https://hookdeck.com/webhooks/grafana/skill))

> Independent reference generated from hookdeck/webhook-registry (commit a24c8d9, 19 Nov 2026). [Grafana's official docs](https://grafana.com/docs/grafana/latest/alerting/configure-notifications/manage-contact-points/integrations/webhook-notifier/).

[Overview](https://hookdeck.com/webhooks/grafana) · [Webhook events (2)](https://hookdeck.com/webhooks/grafana/events) · [MCP events](https://hookdeck.com/webhooks/grafana/mcp-events) · [Verify signatures](https://hookdeck.com/webhooks/grafana/verify) · [Production guide](https://hookdeck.com/webhooks/grafana/guide-duplicates-ordering-retries-timeouts) · [Agent skill](https://hookdeck.com/webhooks/grafana/skill)

## The facts

| Fact | Value | Source |
|---|---|---|
| Signature header | `X-Grafana-Alerting-Signature` Not every delivery is signed: check your setup. | [Grafana docs](https://grafana.com/docs/grafana/latest/alerting/configure-notifications/manage-contact-points/integrations/webhook-notifier/) |
| Scheme | `HMAC-SHA256, hex` | [Grafana docs](https://grafana.com/docs/grafana/latest/alerting/configure-notifications/manage-contact-points/integrations/webhook-notifier/) |
| Signed material | `{raw body}` The request body as sent. If you set a timestamp header on the contact point, Grafana signs {unix seconds}:{raw body} instead: that header's value, a colon, then the body. | [Grafana docs](https://grafana.com/docs/grafana/latest/alerting/configure-notifications/manage-contact-points/integrations/webhook-notifier/) |
| What to build | `Recompute the HMAC over the raw body, or over the timestamp, a colon and the raw body if you set a timestamp header, and compare` | [Grafana docs](https://grafana.com/docs/grafana/latest/alerting/configure-notifications/manage-contact-points/integrations/webhook-notifier/) |
| Key | `shared secret` | [Grafana docs](https://grafana.com/docs/grafana/latest/alerting/configure-notifications/manage-contact-points/integrations/webhook-notifier/) |

## Grafana webhook secret

Each webhook integration on a contact point has its own HMAC secret, which you choose. Grafana doesn't generate one, and nothing is signed until you set it. Keep it in an environment variable, not in source code.

- In the UI: Alerts & IRM > Alerting > Notification configuration > Contact points, edit the contact point, then set Secret under the webhook integration's optional HMAC Signature settings.
- In a provisioning file: `hmacConfig.secret`, with optional `hmacConfig.header` and `hmacConfig.timestampHeader`.
- Format: any string. Grafana uses it as the key as written, with no decoding, and it isn't a Grafana API key or service account token.
- Grafana treats it as a secure field and masks it when the contact point is read back, so keep your own copy.
- Grafana has no test or live split. Test notifications from the contact point are signed with the same secret.
- Rotation: an integration has one secret and no overlap period. Notifications use the new secret as soon as you save it, so accept both on your side during the change.

Source: [Grafana docs](https://grafana.com/docs/grafana/latest/alerting/configure-notifications/manage-contact-points/integrations/webhook-notifier/)

## Code

### Express

From [webhook-skills: skills/grafana-webhooks/examples/express/src/index.js](https://github.com/hookdeck/webhook-skills/blob/9b7c561086c41940e310ef131b09928c1e7508b4/skills/grafana-webhooks/examples/express/src/index.js)

```javascript
// Generated with: grafana-webhooks skill
// https://github.com/hookdeck/webhook-skills
//
// Grafana Alerting webhook contact point receiver.
//
// Grafana signs with HMAC-SHA256 and writes a BARE lowercase hex digest into a
// user-configurable header (default: X-Grafana-Alerting-Signature). There is no
// `sha256=` prefix and no `t=...,v1=...` structure.
//
// What is signed depends on whether the contact point has a Timestamp Header:
//   timestamp header UNSET : HMAC(rawBody)
//   timestamp header SET   : HMAC(timestamp + ":" + rawBody)   <- COLON, seconds
//
// The secret is used AS-IS as UTF-8 bytes: not base64-decoded, no prefix, and not
// a Grafana API key or service-account token.
//
// Grafana sends NO event-type header and NO delivery id. Each request is one
// notification for an alert GROUP; dispatch on `status` / `state` / alerts[].status.

require('dotenv').config();
const express = require('express');
const crypto = require('crypto');

const app = express();

// Both header names are configured on the contact point, so read them from config.
// The signature header has a documented default; the timestamp header has NONE —
// leaving it empty means Grafana signs the body alone.
const SIGNATURE_HEADER = (
  process.env.GRAFANA_SIGNATURE_HEADER || 'X-Grafana-Alerting-Signature'
).toLowerCase();
const TIMESTAMP_HEADER = (process.env.GRAFANA_TIMESTAMP_HEADER || '').toLowerCase();

// Our replay window, not Grafana's — Grafana documents no tolerance. Only
// meaningful when a timestamp header is configured.
const MAX_AGE_SECONDS = Number(process.env.GRAFANA_MAX_AGE_SECONDS || 300);

/**
 * Verify a Grafana Alerting webhook signature.
 *
 * @param {Buffer|string} rawBody - RAW, unparsed request body.
 * @param {string|null} signature - Value of the configured signature header.
 * @param {string|null} timestamp - Value of the configured timestamp header, or null.
 * @param {string|undefined} secret - Contact point HMAC secret, used as-is.
 * @param {{timestampRequired?: boolean, maxAgeSeconds?: number}} [options]
 * @returns {boolean}
 */
function verifyGrafanaSignature(rawBody, signature, timestamp, secret, options = {}) {
  const { timestampRequired = Boolean(TIMESTAMP_HEADER), maxAgeSeconds = MAX_AGE_SECONDS } =
    options;

  // Fail closed: HMAC is optional in Grafana, but it is mandatory here.
  if (!secret || !signature) return false;

  if (timestampRequired) {
    // We're configured for timestamped signing, so a request without the header
    // cannot have been signed the way we expect. Rejecting it stops an attacker
    // from downgrading us to the weaker body-only mode.
    if (!timestamp) return false;

    const ts = Number(timestamp); // UNIX SECONDS (10 digits), never milliseconds
    if (!Number.isFinite(ts)) return false;
    if (Math.abs(Math.floor(Date.now() / 1000) - ts) > maxAgeSeconds) return false;
  }

  const hmac = crypto.createHmac('sha256', secret);
  if (timestampRequired) {
    hmac.update(`${timestamp}:`); // COLON separator — HMAC(timestamp + ":" + body)
  }
  // Hash the RAW bytes. With the Custom Payload option the body may be
  // pretty-printed or not JSON at all, so re-serializing parsed JSON is wrong.
  hmac.update(rawBody);
  const expected = hmac.digest('hex'); // lowercase hex, bare

  // timingSafeEqual THROWS on differing lengths — guard first.
  const received = Buffer.from(String(signature).trim().toLowerCase(), 'utf8');
  const want = Buffer.from(expected, 'utf8');
  if (received.length !== want.length) return false;
  return crypto.timingSafeEqual(received, want);
}

/**
 * Build a heuristic idempotency key. Grafana sends no delivery id, so this is
 * derived from the group identity plus the alert instances it carries. Repeat
 * notifications for an unchanged group hash identically.
 */
function idempotencyKey(payload) {
  const alerts = (payload.alerts || [])
    .map((a) => `${a.fingerprint || ''}@${a.startsAt || ''}`)
    .sort()
    .join(',');
  return `${payload.groupKey || ''}:${payload.status || ''}:${alerts}`;
}

// Grafana webhook endpoint. express.raw() keeps req.body a Buffer so the exact
// bytes Grafana signed are the bytes we hash.
app.post('/webhooks/grafana', express.raw({ type: '*/*' }), (req, res) => {
  const secret = process.env.GRAFANA_WEBHOOK_SECRET;
  if (!secret) {
    // Fail CLOSED. Never silently accept unsigned requests.
    console.error('GRAFANA_WEBHOOK_SECRET is not set — refusing to accept webhooks');
    return res.status(500).send('Webhook secret not configured');
  }

  const signature = req.headers[SIGNATURE_HEADER];
  if (!signature) {
    return res.status(400).send(`Missing ${SIGNATURE_HEADER} header`);
  }

  const timestamp = TIMESTAMP_HEADER ? req.headers[TIMESTAMP_HEADER] : null;

  if (!verifyGrafanaSignature(req.body, signature, timestamp, secret)) {
    console.error('Grafana webhook signature verification failed');
    return res.status(400).send('Invalid signature');
  }

  // Parse only AFTER verification.
  let payload;
  try {
    payload = JSON.parse(req.body.toString('utf8'));
  } catch {
    // A Custom Payload template can render non-JSON. If you use one, handle the
    // body in whatever format your template emits instead.
    return res.status(400).send('Invalid JSON body');
  }

  console.log(
    `Notification from contact point "${payload.receiver}" ` +
      `(status=${payload.status}, state=${payload.state}, key=${idempotencyKey(payload)})`
  );

  if (payload.truncatedAlerts) {
    console.warn(`${payload.truncatedAlerts} alert(s) truncated by Max Alerts`);
  }

  // There are NO event types. Dispatch on the group status...
  switch (payload.status) {
    case 'firing':
      console.log(`FIRING: ${payload.title}`);
      // Your code: open an incident, page on-call, create a ticket
      break;

    case 'resolved':
      console.log(`RESOLVED: ${payload.title}`);
      // Your code: close the incident, post an all-clear
      break;

    default:
      console.log(`Unknown group status: ${payload.status}`);
  }

  // ...and on each alert, because a `firing` GROUP can contain `resolved` alerts
  // (the group is firing if ANY member is firing).
  for (const alert of payload.alerts || []) {
    const name = alert.labels?.alertname || '(unnamed)';
    if (alert.status === 'firing') {
      console.log(`  firing:   ${name} — ${alert.annotations?.summary || ''}`);
    } else if (alert.status === 'resolved') {
      console.log(`  resolved: ${name} (ended ${alert.endsAt})`);
    }
  }

  // Grafana treats any 2xx as success.
  res.status(200).send('OK');
});

app.get('/health', (req, res) => {
  res.json({ status: 'ok' });
});

module.exports = { app, verifyGrafanaSignature, idempotencyKey };

if (require.main === module) {
  const PORT = process.env.PORT || 3000;
  app.listen(PORT, () => {
    console.log(`Server running on http://localhost:${PORT}`);
    console.log(`Webhook endpoint: POST http://localhost:${PORT}/webhooks/grafana`);
    console.log(`Signature header: ${SIGNATURE_HEADER}`);
    console.log(
      TIMESTAMP_HEADER
        ? `Timestamp header: ${TIMESTAMP_HEADER} (signing timestamp + ":" + body)`
        : 'Timestamp header: not configured (signing body only)'
    );
  });
}
```

### Next.js

From [webhook-skills: skills/grafana-webhooks/examples/nextjs/app/webhooks/grafana/route.ts](https://github.com/hookdeck/webhook-skills/blob/9b7c561086c41940e310ef131b09928c1e7508b4/skills/grafana-webhooks/examples/nextjs/app/webhooks/grafana/route.ts)

```typescript
// Generated with: grafana-webhooks skill
// https://github.com/hookdeck/webhook-skills
//
// Grafana Alerting webhook contact point receiver (Next.js App Router).
//
// Grafana signs with HMAC-SHA256 and writes a BARE lowercase hex digest into a
// user-configurable header (default: X-Grafana-Alerting-Signature). There is no
// `sha256=` prefix and no `t=...,v1=...` structure.
//
// What is signed depends on whether the contact point has a Timestamp Header:
//   timestamp header UNSET : HMAC(rawBody)
//   timestamp header SET   : HMAC(timestamp + ":" + rawBody)   <- COLON, seconds
//
// The secret is used AS-IS as UTF-8 bytes: not base64-decoded, no prefix, and not
// a Grafana API key or service-account token.
//
// Grafana sends NO event-type header and NO delivery id. Each request is one
// notification for an alert GROUP; dispatch on `status` / `state` / alerts[].status.

import { NextRequest, NextResponse } from 'next/server';
import crypto from 'crypto';

// Never let a build-time cache serve this route.
export const dynamic = 'force-dynamic';

export interface GrafanaAlert {
  status: 'firing' | 'resolved';
  labels: Record<string, string>;
  annotations: Record<string, string>;
  startsAt: string;
  /** "0001-01-01T00:00:00Z" (Go's zero time) while the alert is still firing. */
  endsAt: string;
  generatorURL?: string;
  fingerprint: string;
  silenceURL?: string;
  dashboardURL?: string;
  panelURL?: string;
  /** Present only when image rendering is configured. */
  imageURL?: string;
  values?: Record<string, number>;
}

export interface GrafanaNotification {
  /** Name of the contact point that delivered this notification. */
  receiver: string;
  /** Group status — `firing` if ANY alert in the group is firing. */
  status: 'firing' | 'resolved';
  orgId: number;
  alerts: GrafanaAlert[];
  groupLabels: Record<string, string>;
  commonLabels: Record<string, string>;
  commonAnnotations: Record<string, string>;
  externalURL: string;
  /** Payload format version — currently "1". */
  version: string;
  groupKey: string;
  /** How many alerts were dropped by the contact point's Max Alerts setting. */
  truncatedAlerts: number;
  title: string;
  state: 'alerting' | 'ok';
  message: string;
}

export interface VerifyOptions {
  timestampRequired?: boolean;
  maxAgeSeconds?: number;
}

/**
 * Read the header names and replay window from the environment.
 *
 * Both header names are configured on the Grafana contact point, so they come
 * from config rather than being hard-coded. The signature header has a
 * documented default; the timestamp header has NONE — leaving it empty means
 * Grafana signs the body alone.
 *
 * Read per request so a serverless instance picks up config without a cold start.
 */
export function getConfig() {
  const timestampHeader = (process.env.GRAFANA_TIMESTAMP_HEADER || '').trim();
  return {
    signatureHeader: (
      process.env.GRAFANA_SIGNATURE_HEADER || 'X-Grafana-Alerting-Signature'
    ).trim(),
    timestampHeader,
    // Our replay window, not Grafana's — Grafana documents no tolerance. Only
    // meaningful when a timestamp header is configured.
    maxAgeSeconds: Number(process.env.GRAFANA_MAX_AGE_SECONDS || 300),
    timestampRequired: Boolean(timestampHeader),
  };
}

/**
 * Verify a Grafana Alerting webhook signature.
 *
 * @param rawBody   RAW, unparsed request body.
 * @param signature Value of the configured signature header.
 * @param timestamp Value of the configured timestamp header, or null.
 * @param secret    Contact point HMAC secret, used as-is.
 */
export function verifyGrafanaSignature(
  rawBody: string | Buffer,
  signature: string | null | undefined,
  timestamp: string | null | undefined,
  secret: string | undefined,
  options: VerifyOptions = {}
): boolean {
  const { timestampRequired = false, maxAgeSeconds = 300 } = options;

  // Fail closed: HMAC is optional in Grafana, but it is mandatory here.
  if (!secret || !signature) return false;

  if (timestampRequired) {
    // We're configured for timestamped signing, so a request without the header
    // cannot have been signed the way we expect. Rejecting it stops an attacker
    // from downgrading us to the weaker body-only mode.
    if (!timestamp) return false;

    const ts = Number(timestamp); // UNIX SECONDS (10 digits), never milliseconds
    if (!Number.isFinite(ts)) return false;
    if (Math.abs(Math.floor(Date.now() / 1000) - ts) > maxAgeSeconds) return false;
  }

  const hmac = crypto.createHmac('sha256', secret);
  if (timestampRequired) {
    hmac.update(`${timestamp}:`); // COLON separator — HMAC(timestamp + ":" + body)
  }
  // Hash the RAW bytes. With the Custom Payload option the body may be
  // pretty-printed or not JSON at all, so re-serializing parsed JSON is wrong.
  hmac.update(rawBody);
  const expected = hmac.digest('hex'); // lowercase hex, bare

  // timingSafeEqual THROWS on differing lengths — guard first.
  const received = Buffer.from(signature.trim().toLowerCase(), 'utf8');
  const want = Buffer.from(expected, 'utf8');
  if (received.length !== want.length) return false;
  return crypto.timingSafeEqual(received, want);
}

/**
 * Build a heuristic idempotency key. Grafana sends no delivery id, so this is
 * derived from the group identity plus the alert instances it carries. Repeat
 * notifications for an unchanged group hash identically.
 */
export function idempotencyKey(payload: Partial<GrafanaNotification>): string {
  const alerts = (payload.alerts || [])
    .map((a) => `${a.fingerprint || ''}@${a.startsAt || ''}`)
    .sort()
    .join(',');
  return `${payload.groupKey || ''}:${payload.status || ''}:${alerts}`;
}

export async function POST(request: NextRequest) {
  const secret = process.env.GRAFANA_WEBHOOK_SECRET;
  if (!secret) {
    // Fail CLOSED. Never silently accept unsigned requests.
    console.error('GRAFANA_WEBHOOK_SECRET is not set — refusing to accept webhooks');
    return NextResponse.json({ error: 'Webhook secret not configured' }, { status: 500 });
  }

  const { signatureHeader, timestampHeader, timestampRequired, maxAgeSeconds } = getConfig();

  // Read the RAW body before anything else — these are the bytes Grafana signed.
  const rawBody = await request.text();

  // Headers.get() is case-insensitive.
  const signature = request.headers.get(signatureHeader);
  if (!signature) {
    return NextResponse.json(
      { error: `Missing ${signatureHeader} header` },
      { status: 400 }
    );
  }

  const timestamp = timestampHeader ? request.headers.get(timestampHeader) : null;

  if (
    !verifyGrafanaSignature(rawBody, signature, timestamp, secret, {
      timestampRequired,
      maxAgeSeconds,
    })
  ) {
    console.error('Grafana webhook signature verification failed');
    return NextResponse.json({ error: 'Invalid signature' }, { status: 400 });
  }

  // Parse only AFTER verification.
  let payload: GrafanaNotification;
  try {
    payload = JSON.parse(rawBody);
  } catch {
    // A Custom Payload template can render non-JSON. If you use one, handle the
    // body in whatever format your template emits instead.
    return NextResponse.json({ error: 'Invalid JSON body' }, { status: 400 });
  }

  console.log(
    `Notification from contact point "${payload.receiver}" ` +
      `(status=${payload.status}, state=${payload.state}, key=${idempotencyKey(payload)})`
  );

  if (payload.truncatedAlerts) {
    console.warn(`${payload.truncatedAlerts} alert(s) truncated by Max Alerts`);
  }

  // There are NO event types. Dispatch on the group status...
  switch (payload.status) {
    case 'firing':
      console.log(`FIRING: ${payload.title}`);
      // Your code: open an incident, page on-call, create a ticket
      break;

    case 'resolved':
      console.log(`RESOLVED: ${payload.title}`);
      // Your code: close the incident, post an all-clear
      break;

    default:
      console.log(`Unknown group status: ${payload.status}`);
  }

  // ...and on each alert, because a `firing` GROUP can contain `resolved` alerts
  // (the group is firing if ANY member is firing).
  for (const alert of payload.alerts || []) {
    const name = alert.labels?.alertname || '(unnamed)';
    if (alert.status === 'firing') {
      console.log(`  firing:   ${name} — ${alert.annotations?.summary || ''}`);
    } else if (alert.status === 'resolved') {
      console.log(`  resolved: ${name} (ended ${alert.endsAt})`);
    }
  }

  // Grafana treats any 2xx as success.
  return NextResponse.json({ received: true });
}
```

### FastAPI

From [webhook-skills: skills/grafana-webhooks/examples/fastapi/main.py](https://github.com/hookdeck/webhook-skills/blob/9b7c561086c41940e310ef131b09928c1e7508b4/skills/grafana-webhooks/examples/fastapi/main.py)

```python
# Generated with: grafana-webhooks skill
# https://github.com/hookdeck/webhook-skills
"""Grafana Alerting webhook contact point receiver.

Grafana signs with HMAC-SHA256 and writes a BARE lowercase hex digest into a
user-configurable header (default: X-Grafana-Alerting-Signature). There is no
``sha256=`` prefix and no ``t=...,v1=...`` structure.

What is signed depends on whether the contact point has a Timestamp Header:

    timestamp header UNSET : HMAC(raw_body)
    timestamp header SET   : HMAC(timestamp + ":" + raw_body)   <- COLON, seconds

Mirrors ``HMACRoundTripper.sign`` in grafana/alerting ``http/hmac.go``::

    hash := hmac.New(sha256.New, []byte(rt.secret))
    if rt.timestampHeader != "" {
        timestamp := strconv.FormatInt(rt.clk.Now().Unix(), 10)
        req.Header.Set(rt.timestampHeader, timestamp)
        hash.Write([]byte(timestamp))
        hash.Write([]byte(":"))
    }
    hash.Write(body)
    signature := hex.EncodeToString(hash.Sum(nil))
    req.Header.Set(rt.header, signature)

The secret is used AS-IS as UTF-8 bytes: not base64-decoded, no prefix, and not a
Grafana API key or service-account token.

Grafana sends NO event-type header and NO delivery id. Each request is one
notification for an alert GROUP; dispatch on ``status`` / ``state`` /
``alerts[].status``.

Grafana publishes no receiver SDK for webhook verification, so this is a manual
implementation -- the same algorithm the Node examples in this skill use.

Covers the Grafana Alerting webhook contact point (Grafana-managed alerting, the
only alerting system in Grafana 11+, and Grafana Cloud). NOT Grafana legacy
dashboard alerting (removed in Grafana 11, different payload, no HMAC), NOT
Grafana OnCall / IRM outgoing webhooks, and NOT Prometheus Alertmanager.
"""

import hashlib
import hmac
import json
import logging
import os
import time
from typing import Any, Mapping, Optional

from dotenv import load_dotenv
from fastapi import FastAPI, Request, Response, status

load_dotenv()

logging.basicConfig(level=logging.INFO)
logger = logging.getLogger("grafana-webhooks")

app = FastAPI(title="Grafana Webhooks")

# Documented default for the contact point's HMAC "Header" field (constant
# `defaultHeaderName` in grafana/alerting http/hmac.go, and the UI placeholder).
DEFAULT_SIGNATURE_HEADER = "X-Grafana-Alerting-Signature"


def get_config() -> dict[str, Any]:
    """Read header names and the replay window from the environment.

    Both header names are configured on the Grafana contact point, so they come
    from config rather than being hard-coded. The signature header has a
    documented default; the timestamp header has NONE -- leaving it empty means
    Grafana signs the body alone.
    """
    timestamp_header = os.environ.get("GRAFANA_TIMESTAMP_HEADER", "").strip()
    return {
        "signature_header": (
            os.environ.get("GRAFANA_SIGNATURE_HEADER") or DEFAULT_SIGNATURE_HEADER
        ).strip(),
        "timestamp_header": timestamp_header,
        # Our replay window, not Grafana's -- Grafana documents no tolerance.
        # Only meaningful when a timestamp header is configured.
        "max_age_seconds": int(os.environ.get("GRAFANA_MAX_AGE_SECONDS", "300")),
        "timestamp_required": bool(timestamp_header),
    }


def verify_grafana_signature(
    raw_body: bytes,
    signature: Optional[str],
    timestamp: Optional[str],
    secret: Optional[str],
    *,
    timestamp_required: bool = False,
    max_age_seconds: int = 300,
) -> bool:
    """Verify a Grafana Alerting webhook signature.

    Args:
        raw_body: RAW, unparsed request body bytes.
        signature: Value of the configured signature header.
        timestamp: Value of the configured timestamp header, or None.
        secret: Contact point HMAC secret, used as-is.
        timestamp_required: True when a Timestamp Header is configured.
        max_age_seconds: Replay window, only applied in timestamped mode.
    """
    # Fail closed: HMAC is optional in Grafana, but it is mandatory here.
    if not secret or not signature:
        return False

    if timestamp_required:
        # We're configured for timestamped signing, so a request without the
        # header cannot have been signed the way we expect. Rejecting it stops
        # an attacker from downgrading us to the weaker body-only mode.
        if not timestamp:
            return False
        try:
            ts = int(timestamp)  # UNIX SECONDS (10 digits), never milliseconds
        except (TypeError, ValueError):
            return False
        if abs(int(time.time()) - ts) > max_age_seconds:
            return False

    mac = hmac.new(secret.encode("utf-8"), digestmod=hashlib.sha256)
    if timestamp_required:
        mac.update(f"{timestamp}:".encode("utf-8"))  # COLON separator
    # Hash the RAW bytes. With the Custom Payload option the body may be
    # pretty-printed or not JSON at all, so re-serializing parsed JSON is wrong.
    mac.update(raw_body)
    expected = mac.hexdigest()  # lowercase hex, bare

    # compare_digest is constant-time and safe on differing lengths. Compare
    # BYTES: with two str arguments it raises TypeError on any non-ASCII
    # character, and header values can carry arbitrary latin-1. Lowercasing the
    # received value is harmless -- Grafana emits lowercase hex.
    received = signature.strip().lower().encode("utf-8", errors="replace")
    return hmac.compare_digest(received, expected.encode("ascii"))


def idempotency_key(payload: Mapping[str, Any]) -> str:
    """Build a heuristic idempotency key.

    Grafana sends no delivery id, so this is derived from the group identity plus
    the alert instances it carries. Repeat notifications for an unchanged group
    hash identically.
    """
    alerts = ",".join(
        sorted(
            f"{alert.get('fingerprint', '')}@{alert.get('startsAt', '')}"
            for alert in payload.get("alerts") or []
        )
    )
    return f"{payload.get('groupKey', '')}:{payload.get('status', '')}:{alerts}"


@app.post("/webhooks/grafana")
async def grafana_webhook(request: Request) -> Response:
    secret = os.environ.get("GRAFANA_WEBHOOK_SECRET")
    if not secret:
        # Fail CLOSED. Never silently accept unsigned requests.
        logger.error("GRAFANA_WEBHOOK_SECRET is not set -- refusing to accept webhooks")
        return Response(
            content="Webhook secret not configured",
            status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
        )

    config = get_config()
    signature_header = config["signature_header"]
    timestamp_header = config["timestamp_header"]

    # Read the RAW body before anything else -- these are the bytes Grafana signed.
    raw_body = await request.body()

    # Starlette header lookup is case-insensitive.
    signature = request.headers.get(signature_header)
    if not signature:
        return Response(
            content=f"Missing {signature_header} header",
            status_code=status.HTTP_400_BAD_REQUEST,
        )

    timestamp = request.headers.get(timestamp_header) if timestamp_header else None

    if not verify_grafana_signature(
        raw_body,
        signature,
        timestamp,
        secret,
        timestamp_required=config["timestamp_required"],
        max_age_seconds=config["max_age_seconds"],
    ):
        logger.error("Grafana webhook signature verification failed")
        return Response(
            content="Invalid signature", status_code=status.HTTP_400_BAD_REQUEST
        )

    # Parse only AFTER verification.
    try:
        payload = json.loads(raw_body)
    except (json.JSONDecodeError, UnicodeDecodeError):
        # A Custom Payload template can render non-JSON. If you use one, handle
        # the body in whatever format your template emits instead.
        return Response(
            content="Invalid JSON body", status_code=status.HTTP_400_BAD_REQUEST
        )

    logger.info(
        'Notification from contact point "%s" (status=%s, state=%s, key=%s)',
        payload.get("receiver"),
        payload.get("status"),
        payload.get("state"),
        idempotency_key(payload),
    )

    if payload.get("truncatedAlerts"):
        logger.warning(
            "%s alert(s) truncated by Max Alerts", payload["truncatedAlerts"]
        )

    # There are NO event types. Dispatch on the group status...
    group_status = payload.get("status")
    if group_status == "firing":
        logger.info("FIRING: %s", payload.get("title"))
        # Your code: open an incident, page on-call, create a ticket
    elif group_status == "resolved":
        logger.info("RESOLVED: %s", payload.get("title"))
        # Your code: close the incident, post an all-clear
    else:
        logger.info("Unknown group status: %s", group_status)

    # ...and on each alert, because a `firing` GROUP can contain `resolved` alerts
    # (the group is firing if ANY member is firing).
    for alert in payload.get("alerts") or []:
        name = (alert.get("labels") or {}).get("alertname", "(unnamed)")
        if alert.get("status") == "firing":
            summary = (alert.get("annotations") or {}).get("summary", "")
            logger.info("  firing:   %s -- %s", name, summary)
        elif alert.get("status") == "resolved":
            logger.info("  resolved: %s (ended %s)", name, alert.get("endsAt"))

    # Grafana treats any 2xx as success.
    return Response(content="OK", status_code=status.HTTP_200_OK)


@app.get("/health")
async def health() -> dict[str, str]:
    return {"status": "ok"}


if __name__ == "__main__":
    import uvicorn

    uvicorn.run(app, host="0.0.0.0", port=int(os.environ.get("PORT", "8000")))
```

Or install the Grafana webhooks skill: `npx skills add hookdeck/webhook-skills --skill grafana-webhooks`

## Common failures

- **No signature header.** The contact point has no HMAC secret, or Grafana is older than 12.0. Other auth settings such as Basic Authentication don't add a signature.
- **Body parsed before verification.** The signature covers the raw bytes Grafana sent. With Custom Payload those bytes can be pretty-printed or not JSON at all, so verify before any body parser runs.
- **Timestamp handled wrongly.** With a timestamp header set, the signed text is the header's value, a colon, then the body. The value is in seconds and the header has no default name, so read the name from your contact point's settings.
- **Header renamed on the contact point.** `X-Grafana-Alerting-Signature` is only the default. If someone set another name in the Header field, your check won't find the signature.

From [Hookdeck's Grafana guide](https://hookdeck.com/webhooks/grafana/guide-duplicates-ordering-retries-timeouts).

---

Not affiliated with Grafana. Facts are compiled from public sources and linked inline. [View as JSON](https://hookdeck.com/webhooks/grafana.json) · [Report a correction](https://hookdeck.com/contact)
