* Template editor syntax highlighting when preview is json-like
* Add new template editor language examples, snippets, and functions
* Use updated NewTemplate function
* Add new fields to webhook notifier
- CustomPayload
- ExtraHeaders
* Documentation
* Update grafana/alerting to in-progress PR (needs updating after merge)
* Fix integration test
* Remove docs reference to .Extra template context
No longer exists, was part of a previous iteration
* make update-workspace
* Update grafana/alerting to actual merged commit
@ -115,18 +121,11 @@ To validate incoming webhook requests from Grafana, follow these steps:
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). |
{{<admonitiontype="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.
| 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. |
#### Optional notification settings
@ -134,7 +133,7 @@ If you need to format these fields as JSON or modify other webhook request optio
| Disable resolved message | Enable this option to prevent notifications when an alert resolves. |
## JSON payload
## Default JSON payload
The following example shows the payload of a webhook notification containing information about two firing alerts:
@ -252,3 +251,71 @@ The Alert object represents an alert included in the notification group, as prov
| `dashboardURL` | string | A link to the Grafana Dashboard if the alert has a Dashboard UID annotation. |
| `panelURL` | string | A link to the panel if the alert has a Panel ID annotation. |
| `imageURL` | string | URL of a screenshot of a panel assigned to the rule that created this notification. |
## Custom Payload
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).
| `Receiver` | string | The name of the contact point sending the notification |
| `Status` | string | The status is `firing` if at least one alert is firing, otherwise `resolved`. |
| `Alerts` | [][Alert](#alert) | List of all firing and resolved alerts in this notification. |
| `Alerts.Firing` | [][Alert](#alert) | List of all firing alerts in this notification. |
| `Alerts.Resolved` | [][Alert](#alert) | List of all resolved alerts in this notification. |
| `GroupLabels` | [KV](#kv) | The labels that group these alerts in this notification based on the `Group by` option. |
| `CommonLabels` | [KV](#kv) | The labels common to all alerts in this notification. |
| `CommonAnnotations` | [KV](#kv) | The annotations common to all alerts in this notification. |
| `ExternalURL` | string | A link to Grafana, or the Alertmanager that sent this notification if using an external Alertmanager. |
| `GroupKey` | string | The key used to identify this alert group. |
| `TruncatedAlerts` | integer | The number of alerts, if any, that were truncated in the notification. Supported by Webhook and OnCall. |
It's important to remember that [a single notification can group multiple alerts](ref:alert-grouping) to reduce the number of alerts you receive. `Alerts` is an array that includes all the alerts in the notification.
@ -115,6 +117,7 @@ Grafana-managed alerts include these additional properties:
| `SilenceURL` | string | A link to silence the alert. |
| `Values` | [KV](#kv) | The values of expressions used to evaluate the alert condition. Only relevant values are included. |
| `ValueString` | string | A string that contains the labels and value of each reduced expression in the alert. |
| `OrgID` | integer | The ID of the organization that owns the alert. |
This example iterates over the list of firing and resolved alerts (`.Alerts`) in the notification and prints the data for each alert:
@ -264,6 +267,176 @@ You can then use `tz` to change the timezone from UTC to local time, such as `Eu
21:01:45 CET
```
## Namespaced Functions
In addition to the top-level functions, the following namespaced functions are also available:
| `coll.Dict` | key string, value any, ... | map | Creates a map with string keys from key/value pairs. All keys are converted to strings. If an odd number of arguments is provided, the last key will have an empty string value. |
| `coll.Slice` | ...any | []any | Creates a slice (array/list) from the provided arguments. Useful for creating lists that can be iterated over with `range`. |
| `coll.Append` | value any, list []any | []any | Creates a new list by appending a value to the end of an existing list. Does not modify the original list. |
Example using collection functions:
```go
{{ define "collection.example" }}
{{- /* Create a dictionary of alert metadata */ -}}
| `data.JSON` | jsonString string | any | Parses a JSON string into an object that can be manipulated in the template. Works with both JSON objects and arrays. |
| `data.ToJSON` | obj any | string | Serializes any object (maps, arrays, etc.) into a JSON string. Useful for creating webhook payloads. |
| `data.ToJSONPretty` | indent string, obj any | string | Creates an indented JSON string representation of an object. The first argument specifies the indentation string (e.g., spaces). |
Example using data functions:
```go
{{ define "data.example" }}
{{- /* First, let's create some alert data as a JSON string */ -}}
{{ $jsonString := `{
"service": {
"name": "payment-api",
"environment": "production",
"thresholds": {
"error_rate": 5,
"latency_ms": 100
}
}
}` }}
{{- /* Parse the JSON string into an object we can work with */ -}}
| `tmpl.Exec` | name string, [context any] | string | Executes a named template and returns the result as a string. Similar to the `template` action but allows for post-processing of the result. |
| `tmpl.Inline` | template string, context any | string | Renders a string as a template. |
| `time.Now` | | Time | Returns the current local time as a time.Time object. Can be formatted using Go's time formatting functions. |
Example using time functions:
```go
{{ define "time.example" }}
{{- /* Get current time in different formats */ -}}
Current Time (UTC): {{ (time.Now).UTC.Format "2006-01-02 15:04:05 MST" }}
Current Time (Local): {{ (time.Now).Format "Monday, January 2, 2006 at 15:04:05" }}
{{- /* Compare alert time with current time */ -}}
{{ $timeAgo := (time.Now).Sub .StartsAt }}
Alert fired: {{ $timeAgo }} ago
{{ end }}
```
Output:
```
Current Time (UTC): 2025-03-08 18:14:27 UTC
Current Time (Local): Saturday, March 8, 2025 at 14:14:27
Alert fired: 25h49m32.78574723s ago
```
## Differences with annotation and label templates
In the alert rule, you can also template annotations and labels to include additional information. For example, you might add a `summary` annotation that displays the query value triggering the alert.
// list of available Gomplate functions in Alertmanager templates
// see https://github.com/hairyhenderson/gomplate
exportconstGomplateFunctions={
coll:[
{
keyword:'coll.Dict',
definition:
'Creates a map with string keys from key/value pairs. All keys are converted to strings. If an odd number of arguments is provided, the last is used as the key with an empty string value.',
'Execute (render) the named template. This is equivalent to using the `template` action, except the result is returned as a string. This allows for post-processing of templates.',
usage:'function(name string, [context any])',
example:`{{ tmpl.Exec "T1" | strings.ToUpper }}`,
},
{
keyword:'tmpl.Inline',
definition:
'Render the given string as a template, just like a nested template. If the template is given a name, it can be re-used later with the `template` keyword. A context can be provided, otherwise the default gomplate context will be used.',
Matthew Jacobson
3 months ago
committed by