# Grafana webhooks

Grafana webhooks are HTTP requests that a Webhook contact point in Grafana Alerting sends to your URL when a group of alerts fires or resolves.

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)

## Key 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/) |
| How events are identified | `status field in the body (firing or resolved); no event types` | [Grafana docs](https://grafana.com/docs/grafana/latest/alerting/configure-notifications/manage-contact-points/integrations/webhook-notifier/) |
| Body format | `JSON` Content type: application/json. | [Grafana docs](https://grafana.com/docs/grafana/latest/alerting/configure-notifications/manage-contact-points/integrations/webhook-notifier/) |
| API versioning | `version in the body` Seen: 1. | [Grafana docs](https://grafana.com/docs/grafana/latest/alerting/configure-notifications/manage-contact-points/integrations/webhook-notifier/) |
| Envelope | `receiver, status, orgId, alerts, groupLabels, commonLabels, commonAnnotations, externalURL, version, groupKey, truncatedAlerts, title, state, message` | [Grafana docs](https://grafana.com/docs/grafana/latest/alerting/configure-notifications/manage-contact-points/integrations/webhook-notifier/) |
| Agent skill | `npx skills add hookdeck/webhook-skills --skill grafana-webhooks` | [Agent skill →](https://hookdeck.com/webhooks/grafana/skill) |

[Verify Grafana webhooks](https://hookdeck.com/webhooks/grafana/verify)

## How Grafana webhooks work

Webhooks push alerts to your system as their state changes, so you don't have to poll Grafana for them. A notification policy groups alerts by label and routes each group to a contact point, and each group's notification is one HTTP request with a JSON body, `POST` by default. By default Grafana sends the first notification 30 seconds after a group appears, then at most every 5 minutes while the group changes, and repeats an unchanged group every 4 hours.

Grafana has no event types. The top-level `status` field is `firing` if any alert in the group is firing and `resolved` once all of them have resolved, and each entry in `alerts[]` has its own `status`, so a `firing` notification can carry resolved alerts. `version` is the payload version, currently `"1"`. The Custom Payload option replaces this body with whatever your template renders.

## Setting up Grafana webhooks

- Create a contact point under Alerts & IRM > Alerting > Notification configuration > Contact points, choose the Webhook integration and enter your URL. You can also create one in a provisioning file. Then assign it to a notification policy or an alert rule, or it won't receive anything.
- Test it with the Test button on the contact point, which sends a `firing` notification with a synthetic alert. To reach your own machine from Grafana Cloud you'll need a public URL, such as a tunnel.
- Check results on the Contact points tab, which shows the status of the latest deliveries, and on the History page's Notifications tab. Grafana OSS and Enterprise need Loki for that history.
- Grafana has no way to resend a notification by hand. A failed one is tried again at the group's next interval, as long as the group still has alerts.

## Delivery behaviour

- **Timeout:** 30 seconds. fixed in Grafana's HTTP client, with no contact point setting. [Guide](https://hookdeck.com/webhooks/grafana/guide-duplicates-ordering-retries-timeouts#timeouts)
- **Retries:** at the next group interval. no immediate retry; the default interval is 5 minutes. [Guide](https://hookdeck.com/webhooks/grafana/guide-duplicates-ordering-retries-timeouts#retries)
- **After repeated failures:** resolved alerts dropped. after 3 group intervals; firing alerts keep being tried. [Guide](https://hookdeck.com/webhooks/grafana/guide-duplicates-ordering-retries-timeouts#retries)
- **Duplicates:** expected. unchanged groups repeat every 4 hours by default, and HA can double-send. [Guide](https://hookdeck.com/webhooks/grafana/guide-duplicates-ordering-retries-timeouts#duplicates)

## Known failure modes

1. **Repeated notifications.** Grafana resends an unchanged group every 4 hours by default, and its high availability setup can send duplicates. Skip an alert you've already processed, using `fingerprint`, `startsAt` and `status` as the key. [Handle duplicates](https://hookdeck.com/webhooks/grafana/guide-duplicates-ordering-retries-timeouts#duplicates)
2. **A resolved notification never arrives.** If your endpoint keeps failing, Grafana drops resolved alerts after 3 group intervals, 15 minutes by default, so you never hear they ended. Expire open incidents on your side rather than waiting for `resolved`. [Retries and lost notifications](https://hookdeck.com/webhooks/grafana/guide-duplicates-ordering-retries-timeouts#retries)
3. **Timeouts after 30 seconds.** Grafana abandons a request after 30 seconds and you can't change that on a contact point. Return a 2xx first, because a slow handler that finishes its work still gets the group sent again. [Timeouts](https://hookdeck.com/webhooks/grafana/guide-duplicates-ordering-retries-timeouts#timeouts)
4. **Out-of-order or mixed notifications.** Grafana's docs say high availability can cause out-of-order notifications, and a `firing` body can hold resolved alerts. Read each alert's `status`, and compare `startsAt` with what you've stored for that `fingerprint`. [Handle ordering](https://hookdeck.com/webhooks/grafana/guide-duplicates-ordering-retries-timeouts#ordering)

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

## Grafana webhook best practices

- **[Turn on signing and require it](https://hookdeck.com/webhooks/grafana/verify).** Signing is off until you set a secret. Once it's on, reject a request with no signature header, because anyone who finds your URL can send a false all-clear.
- **[Respond within 30 seconds](https://hookdeck.com/webhooks/grafana/guide-duplicates-ordering-retries-timeouts#timeouts).** The limit is fixed and covers the whole request. Return a 2xx first and do the work in a background job.
- **[Process each alert, not just the group](https://hookdeck.com/webhooks/grafana/guide-duplicates-ordering-retries-timeouts#ordering).** A `firing` notification can carry resolved alerts, so read `alerts[].status` rather than the top-level `status`.
- **[Deduplicate on the fingerprint and start time](https://hookdeck.com/webhooks/grafana/guide-duplicates-ordering-retries-timeouts#duplicates).** There's no delivery ID, and `fingerprint` stays the same each time an alert with those labels fires. Key on `fingerprint`, `startsAt` and `status` together.
- **[Don't wait for a resolved notification](https://hookdeck.com/webhooks/grafana/guide-duplicates-ordering-retries-timeouts#retries).** A resolved notification can be dropped during an outage. Expire open incidents that stop receiving the repeat reminder, and check Grafana's active alerts.
- **[Control volume with notification policies](https://hookdeck.com/webhooks/grafana/guide-duplicates-ordering-retries-timeouts#choosing-events).** You can't subscribe to event types. Route by label, set Group by and the timers, and use Max Alerts if bodies get too large.

## Common Grafana webhook events

### Alert group status

- [firing](https://hookdeck.com/webhooks/grafana/events#firing): At least one alert in the group is firing
- [resolved](https://hookdeck.com/webhooks/grafana/events#resolved): Every alert in the group has resolved

## Events

| Resource | Events | Payloads |
|---|---|---|
| [Grafana events](https://hookdeck.com/webhooks/grafana/events#resource-other) | 2 | 1 |

[All 2 events](https://hookdeck.com/webhooks/grafana/events)

## In this hub

- [Webhook events](https://hookdeck.com/webhooks/grafana/events): Every covered Grafana event, with payloads where the registry has them.
- [MCP events](https://hookdeck.com/webhooks/grafana/mcp-events): How an agent subscribes to Grafana events as MCP events.
- [Verify signatures](https://hookdeck.com/webhooks/grafana/verify): Signature facts, verification code and common failures.
- [Production guide](https://hookdeck.com/webhooks/grafana/guide-duplicates-ordering-retries-timeouts): Production problems: timeouts, duplicates, ordering and retries, and how to handle them.
- [Agent skill](https://hookdeck.com/webhooks/grafana/skill): Install the webhook skill in your coding agent. `npx skills add hookdeck/webhook-skills --skill grafana-webhooks`
---

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)
