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.
For more details on contact points, including how to test them and enable notifications, refer to [Configure contact points](ref:configure-contact-points).
| Authentication Header Scheme | Scheme for the `Authorization` Request Header. Default is `Bearer`. |
| Authentication Header Credentials | Credentials for the `Authorization` Request header. |
| Extra Headers | Additional HTTP headers to include in the request. You can also override the default `Content-Type: application/json` header to specify a different content type for the request payload. |
| Max Alerts | Maximum number of alerts to include in a notification. Any alerts exceeding this limit are ignored. `0` means no limit. |
| TLS | TLS configuration options, including CA certificate, client certificate, and client key. |
You can secure your webhook notifications using HMAC signatures to verify the authenticity and integrity of the requests. When enabled, Grafana signs the webhook payload with a shared secret using HMAC-SHA256.
| Secret | The shared secret key used to generate the HMAC signature. |
| Header | The HTTP header where the signature will be set. Default is `X-Grafana-Alerting-Signature`. |
| Timestamp Header | Optional header to include a timestamp in the signature calculation. When specified, Grafana will set a Unix timestamp in this header and include it in the HMAC calculation. This provides protection against replay attacks. |
When HMAC signing is configured, Grafana generates a signature using HMAC-SHA256 with your secret key. If a timestamp header is specified, a Unix timestamp is included in the signature calculation. The signature is calculated as:
```
HMAC(timestamp + ":" + body)
```
The timestamp is sent in the specified header. If no timestamp header is specified, the signature is calculated just from the request body. The signature is sent as a hex-encoded string in the specified signature header.
##### Validate a request
To validate incoming webhook requests from Grafana, follow these steps:
1. Extract the signature from the header (default is `X-Grafana-Alerting-Signature`).
2. If you configured a timestamp header, extract the timestamp value and verify it's recent to prevent replay attacks.
3. Calculate the expected signature:
- Create an HMAC-SHA256 hash using your shared secret
- If using timestamps, include the timestamp followed by a colon (`:`) before the request body
- Hash the raw request body
- Convert the result to a hexadecimal string
4. Compare the calculated signature with the one in the request header.
Use the following settings to include custom data within the [JSON payload](#body). Both options support using [notification templates](ref:notification-templates).
| Title | Sends the value as a string in the `title` field of the [JSON payload](#body). Supports [notification templates](ref:notification-templates). |
| Message | Sends the value as a string in the `message` field of the [JSON payload](#body). Supports [notification templates](ref:notification-templates). |
| [Custom Payload](#custom-payload) | Optionally override the default payload format with a custom template. |
"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"
| `receiver` | string | Name of the contact point. |
| `status` | string | Current status of the alert, `firing` or `resolved`. |
| `orgId` | number | ID of the organization related to the payload. |
| `alerts` | array of [alerts](#alert) | Alerts that are triggering. |
| `groupLabels` | object | Labels that are used for grouping, map of string keys to string values. |
| `commonLabels` | object | Labels that all alarms have in common, map of string keys to string values. |
| `commonAnnotations` | object | Annotations that all alarms have in common, map of string keys to string values. |
| `externalURL` | string | External URL to the Grafana instance sending this webhook. |
| `version` | string | Version of the payload structure. |
| `groupKey` | string | Key that is used for grouping. |
| `truncatedAlerts` | number | Number of alerts that were truncated. |
| `state` | string | State 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](#optional-settings-using-templates).
The `Custom Payload` option allows you to completely customize the webhook payload using templates. This gives you full control over the structure and content of the webhook request.
| Payload Template | Template string that defines the structure of the webhook payload. |
| Payload Variables | Key-value pairs that define additional variables available in the template under `.Vars.<variable_name>`. |
Example of a custom payload template that includes variables:
```
{
"alert_name": "{{ .CommonLabels.alertname }}",
"status": "{{ .Status }}",
"environment": "{{ .Vars.environment }}",
"custom_field": "{{ .Vars.custom_field }}"
}
```
{{<admonitiontype="note">}}
When using Custom Payload, the Title and Message fields are ignored as the entire payload structure is determined by your template.
{{</admonition>}}
### JSON Template Functions
When creating custom payloads, several template functions are available to help generate valid JSON structures. These include functions for creating dictionaries (`coll.Dict`), arrays (`coll.Slice`, `coll.Append`), and converting between JSON strings and objects (`data.ToJSON`, `data.JSON`).
For detailed information about these and other template functions, refer to [notification template functions](ref:notification-templates-namespaced-functions).
