Configure the webhook notifier for Alerting
Grafana Cloud Enterprise Open source

Configure webhook notifications

Use the webhook integration in contact points to send alert notifications to your webhook.

The webhook integration is a flexible way to integrate alerts into your system. When a notification is triggered, it sends a JSON request with alert details and additional data to the webhook endpoint.

Configure webhook for a contact point

To create a contact point with webhook integration, complete the following steps.

  1. Navigate to Alerts & IRM -> Alerting -> Contact points.
  2. Click + Add contact point.
  3. Enter a name for the contact point.
  4. From the Integration list, select Webhook.
  5. In the URL field, copy in your Webhook URL.
  6. (Optional) Configure additional settings.
  7. Click Save contact point.

For more details on contact points, including how to test them and enable notifications, refer to Configure contact points.

Webhook settings

OptionDescription
URLThe Webhook URL.

Optional settings

OptionDescription
HTTP MethodSpecifies the HTTP method to use: POST or PUT.
Basic Authentication UsernameUsername for HTTP Basic Authentication.
Basic Authentication PasswordPassword for HTTP Basic Authentication.
Authentication Header SchemeScheme for the Authorization Request Header. Default is Bearer.
Authentication Header CredentialsCredentials for the Authorization Request header.
Max AlertsMaximum number of alerts to include in a notification. Any alerts exceeding this limit are ignored. 0 means no limit.
TLSTLS configuration options, including CA certificate, client certificate, and client key.

Note

You can configure either HTTP Basic Authentication or the Authorization request header, but not both.

Optional settings using templates

Use the following settings to include custom data within the JSON payload. Both options support using notification templates.

OptionDescription
TitleSends the value as a string in the title field of the JSON payload. Supports notification templates.
MessageSends the value as a string in the message field of the JSON payload. Supports notification templates.

Note

You can customize the title and message options to include custom messages and notification data using notification templates. These fields are always sent as strings in the JSON payload.

However, you cannot customize the webhook data structure, such as adding or changing other JSON fields and HTTP headers, or sending data in a different format like XML.

If you need to format these fields as JSON or modify other webhook request options, consider sending webhook notifications to a proxy server that adjusts the webhook request before forwarding it to the final destination.

Optional notification settings

OptionDescription
Disable resolved messageEnable this option to prevent notifications when an alert resolves.

JSON payload

The following example shows the payload of a webhook notification containing information about two firing alerts:

json
{
  "receiver": "My Super Webhook",
  "status": "firing",
  "orgId": 1,
  "alerts": [
    {
      "status": "firing",
      "labels": {
        "alertname": "High memory usage",
        "team": "blue",
        "zone": "us-1"
      },
      "annotations": {
        "description": "The system has high memory usage",
        "runbook_url": "https://myrunbook.com/runbook/1234",
        "summary": "This alert was triggered for zone us-1"
      },
      "startsAt": "2021-10-12T09:51:03.157076+02:00",
      "endsAt": "0001-01-01T00:00:00Z",
      "generatorURL": "https://play.grafana.org/alerting/1afz29v7z/edit",
      "fingerprint": "c6eadffa33fcdf37",
      "silenceURL": "https://play.grafana.org/alerting/silence/new?alertmanager=grafana&matchers=alertname%3DT2%2Cteam%3Dblue%2Czone%3Dus-1",
      "dashboardURL": "",
      "panelURL": "",
      "values": {
        "B": 44.23943737541908,
        "C": 1
      }
    },
    {
      "status": "firing",
      "labels": {
        "alertname": "High CPU usage",
        "team": "blue",
        "zone": "eu-1"
      },
      "annotations": {
        "description": "The system has high CPU usage",
        "runbook_url": "https://myrunbook.com/runbook/1234",
        "summary": "This alert was triggered for zone eu-1"
      },
      "startsAt": "2021-10-12T09:56:03.157076+02:00",
      "endsAt": "0001-01-01T00:00:00Z",
      "generatorURL": "https://play.grafana.org/alerting/d1rdpdv7k/edit",
      "fingerprint": "bc97ff14869b13e3",
      "silenceURL": "https://play.grafana.org/alerting/silence/new?alertmanager=grafana&matchers=alertname%3DT1%2Cteam%3Dblue%2Czone%3Deu-1",
      "dashboardURL": "",
      "panelURL": "",
      "values": {
        "B": 44.23943737541908,
        "C": 1
      }
    }
  ],
  "groupLabels": {},
  "commonLabels": {
    "team": "blue"
  },
  "commonAnnotations": {},
  "externalURL": "https://play.grafana.org/",
  "version": "1",
  "groupKey": "{}:{}",
  "truncatedAlerts": 0,
  "title": "[FIRING:2]  (blue)",
  "state": "alerting",
  "message": "**Firing**\n\nLabels:\n - alertname = T2\n - team = blue\n - zone = us-1\nAnnotations:\n - description = This is the alert rule checking the second system\n - runbook_url = https://myrunbook.com\n - summary = This is my summary\nSource: https://play.grafana.org/alerting/1afz29v7z/edit\nSilence: https://play.grafana.org/alerting/silence/new?alertmanager=grafana&matchers=alertname%3DT2%2Cteam%3Dblue%2Czone%3Dus-1\n\nLabels:\n - alertname = T1\n - team = blue\n - zone = eu-1\nAnnotations:\nSource: https://play.grafana.org/alerting/d1rdpdv7k/edit\nSilence: https://play.grafana.org/alerting/silence/new?alertmanager=grafana&matchers=alertname%3DT1%2Cteam%3Dblue%2Czone%3Deu-1\n"
}

Body

The JSON payload of webhook notifications includes the following key-value pairs:

KeyTypeDescription
receiverstringName of the contact point.
statusstringCurrent status of the alert, firing or resolved.
orgIdnumberID of the organization related to the payload.
alertsarray of alertsAlerts that are triggering.
groupLabelsobjectLabels that are used for grouping, map of string keys to string values.
commonLabelsobjectLabels that all alarms have in common, map of string keys to string values.
commonAnnotationsobjectAnnotations that all alarms have in common, map of string keys to string values.
externalURLstringExternal URL to the Grafana instance sending this webhook.
versionstringVersion of the payload structure.
groupKeystringKey that is used for grouping.
truncatedAlertsnumberNumber of alerts that were truncated.
statestringState of the alert group (either alerting or ok).

The following key-value pairs are also included in the JSON payload and can be configured in the webhook settings using notification templates.

KeyTypeDescription
titlestringCustom title. Configurable in webhook settings using notification templates.
messagestringCustom message. Configurable in webhook settings using notification templates.

Alert

The Alert object represents an alert included in the notification group, as provided by the alerts field.

KeyTypeDescription
statusstringCurrent status of the alert, firing or resolved.
labelsobjectLabels that are part of this alert, map of string keys to string values.
annotationsobjectAnnotations that are part of this alert, map of string keys to string values.
startsAtstringStart time of the alert.
endsAtstringEnd time of the alert, default value when not resolved is 0001-01-01T00:00:00Z.
valuesobjectValues that triggered the current status.
generatorURLstringURL of the alert rule in the Grafana UI.
fingerprintstringThe labels fingerprint, alarms with the same labels will have the same fingerprint.
silenceURLstringURL to silence the alert rule in the Grafana UI.
dashboardURLstringA link to the Grafana Dashboard if the alert has a Dashboard UID annotation.
panelURLstringA link to the panel if the alert has a Panel ID annotation.
imageURLstringURL of a screenshot of a panel assigned to the rule that created this notification.