Grafana webhook contact point: alert payload, Test button, HMAC and auth

Grafana Alerting sends notifications to any HTTP endpoint as a JSON POST or PUT through a contact point of type Webhook. The quickest way to see the exact JSON Grafana sends is to put a free bin URL in the contact point and send a test notification. There's no signup, and the bin stays live for 48 hours and accepts 100 requests a day. Below we walk through setting up and testing a Grafana webhook contact point, the payload fields, authentication, the HMAC signature, and templates.

Send a Grafana test alert to a bin

1. Open view.webhooks.page in your browser to create a free bin, or run curl -X POST https://webhooks.sh/v1/bins to get an ingest_url and view_url.
2. In Grafana, go to Alerts & IRM > Alerting > Notification configuration > Contact points and select + Add contact point.
3. Give it a name, select Webhook in the Integration list, paste the bin's ingest URL (any path like /grafana works too), and select Save contact point.
4. Edit the contact point, select Test, keep the predefined test notification or enter your own annotations and labels, and select Send test notification.

The request arrives live in the bin viewer with its method, headers and JSON body. The Test button only works when you're using the Grafana Alertmanager, and you can also check the status of the latest deliveries on the Contact points tab.

If you want to leave the bin URL in your contact point past 48 hours, claim the bin from the viewer with a free Google sign-in before it expires. The URL stays the same, requests are kept for 30 days on a rolling basis, and the limit stays at 100 requests a day.

# 1. Create a free bin (or open view.webhooks.page)
curl -X POST https://webhooks.sh/v1/bins

# 2. Contact point > Integration: Webhook
#    URL: https://<bin>.webhooks.page/grafana
# 3. Edit > Test > Send test notification, then read it:
curl -H "x-view-key: <view key>" \
  https://view.webhooks.page/api/bins/<bin>/deliveries

The JSON a Grafana webhook sends

Grafana sends a single JSON object per notification. At the top level, status is firing or resolved, alerts holds the array of individual alerts with their labels, annotations, start and end times and values, and any labels and annotations shared across every alert in the batch are repeated in commonLabels and commonAnnotations. While an alert is still active, its endsAt field stays set to 0001-01-01T00:00:00Z. If you set Max Alerts on the contact point (0 means no limit), truncatedAlerts counts how many alerts were left out of the array.

The table below lists the fields in the Grafana webhook payload, followed by an excerpt of Grafana's documented example with the second alert omitted.

{
  "receiver": "My Super Webhook",
  "status": "firing",
  "orgId": 1,
  "alerts": [
    {
      "status": "firing",
      "labels": {
        "alertname": "High memory usage",
        "team": "blue",
        "zone": "us-1"
      },
      "annotations": {
        "summary": "This alert was triggered for zone us-1"
      },
      "startsAt": "2021-10-12T09:51:03.157076+02:00",
      "endsAt": "0001-01-01T00:00:00Z",
      "fingerprint": "c6eadffa33fcdf37",
      "values": { "B": 44.23943737541908, "C": 1 }
    }
  ],
  "commonLabels": { "team": "blue" },
  "externalURL": "https://play.grafana.org/",
  "truncatedAlerts": 0,
  "state": "alerting",
  "title": "[FIRING:2]  (blue)"
}

Authentication and what a bin shows

A Grafana webhook contact point supports three built-in ways to authenticate:

• Basic Authentication with a username and password.
• An Authorization header with a scheme (Bearer by default) and credentials.
• OAuth2 client credentials, where Grafana fetches a token from the token URL with your client ID and secret and sends it as a Bearer token.

You can't set Basic Authentication and the Authorization header at the same time, and if you configure OAuth2 it takes precedence over both.

All three methods send credentials in the Authorization header. In a free bin, any header whose name contains authorization, cookie, key, token or secret shows up as redacted, so you can confirm that Grafana sent the header without exposing the secret in the browser. Any Extra Headers you configure stay visible in full unless their names match one of those words.

Don't put tokens in the webhook URL itself. Grafana stores the URL in plain text and doesn't mask it when someone reads the contact point back, unlike the authentication fields, which are stored securely and masked. A webhooks.sh ingest URL doesn't need a secret in it anyway, since reading the captured requests requires the separate view_url.

Check the HMAC signature

When you enable HMAC Signature on the contact point and set a shared secret, Grafana signs the request body with HMAC-SHA256 and sends the hex-encoded digest in X-Grafana-Alerting-Signature (or in another header name you pick). If you also configure a Timestamp Header, Grafana puts a Unix timestamp in that header and signs timestamp + ":" + body instead of the body alone, so your receiver can reject old requests.

Because X-Grafana-Alerting-Signature doesn't match the redacted header names, its full value is visible in a bin. You can copy the signature and raw body from a captured test alert into the HMAC signature verifier to check your secret and timestamp settings before you write any receiver code.

import hashlib, hmac

def valid(body: bytes, sig: str, secret: str, ts: str = "") -> bool:
    msg = (ts + ":").encode() + body if ts else body
    mac = hmac.new(secret.encode(), msg, hashlib.sha256)
    return hmac.compare_digest(mac.hexdigest(), sig)

Templates, Max Alerts and custom payloads

The Title and Message settings populate the top-level title and message fields in the JSON and accept notification templates. If you need a different JSON shape altogether, Custom Payload replaces the entire request body with a template, ignores Title and Message, and exposes any Payload Variables you define as .Vars.<name> (note that Custom Payload isn't generally available in Grafana Cloud yet).

Notification templates are easy to get slightly wrong, especially when quoting values inside JSON, so send a test notification to your bin after each edit and check the rendered body. Two other settings change what arrives at your endpoint: Max Alerts caps how many alerts go into a single notification (0 means no limit), and Disable resolved message stops Grafana from sending a notification when an alert resolves.

FAQ

How do I test a Grafana webhook contact point?

Edit the contact point, select Test, and click Send test notification. This option is only available for the Grafana Alertmanager. Point the contact point at a free bin URL first to see the JSON request arrive live in your browser.

What does a Grafana alert webhook payload contain?

The top-level JSON object contains receiver, status, orgId, alerts, groupLabels, commonLabels, commonAnnotations, externalURL, version, groupKey, truncatedAlerts, state, title and message. Each item in alerts includes status, labels, annotations, startsAt, endsAt, values, fingerprint and the alert URLs (generatorURL, silenceURL, dashboardURL, panelURL and imageURL).

How do I add authentication to a Grafana webhook?

Configure Basic Authentication, an Authorization header with a scheme (Bearer by default) and credentials, or OAuth2 client credentials, which take precedence over the other two. Avoid putting tokens in the webhook URL, because Grafana stores the URL in plain text and shows it unmasked.

How do I verify a Grafana webhook signature?

Compute the HMAC-SHA256 of the raw request body (or <timestamp>:<body> if you configured a Timestamp Header) using your shared secret, hex-encode the result, and compare it to the X-Grafana-Alerting-Signature header.

Can I change the JSON Grafana sends to a webhook?

Yes. Title and Message accept notification templates for the title and message fields, and Custom Payload lets you replace the entire JSON body with a template (though Custom Payload is not yet generally available in Grafana Cloud).