[release-12.2.2] docs(alerting): clarify usage of templates in webhook custom payloads (#112755)

docs(alerting): clarify usage of templates in webhook custom payloads (#112672) * docs(alerting): clarify usage of templates in webhook custom payloads * Update docs/sources/alerting/configure-notifications/template-notifications/manage-notification-templates.md --------- (cherry picked from commit fb5c5411f8) Co-authored-by: Pepe Cano <825430+ppcano@users.noreply.github.com> Co-authored-by: Johnny Kartheiser <140559259+JohnnyK-Grafana@users.noreply.github.com>
2025-10-21 18:49:20 +00:00
parent 569738c316
commit 470edab706
3 changed files with 10 additions and 8 deletions
@@ -241,17 +241,20 @@ The Alert object represents an alert included in the notification group, as prov

 ## Custom Payload

+The `Custom Payload` option allows you to completely customize the webhook payload using [templates](ref:notification-templates). This gives you full control over the structure and content of the webhook request.
+
+For detailed information about how to create and manage notification templates, refer to [notification templates](ref:notification-templates).
+
 {{< admonition type="note" >}}

-Custom Payload is not yet [generally available](https://grafana.com/docs/release-life-cycle/#general-availability) in Grafana Cloud.
+- When using Custom Payload, the [`Title` and `Message` fields](#optional-notification-settings) are ignored as the entire payload structure is determined by your template.
+- Custom Payload is not yet [generally available](https://grafana.com/docs/release-life-cycle/#general-availability) in Grafana Cloud.

 {{< /admonition >}}

-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.
-
 | Option            | Description                                                                                               |
 | ----------------- | --------------------------------------------------------------------------------------------------------- |
-| Payload Template  | Template string that defines the structure of the webhook payload.                                        |
+| Payload Template  | [Notification template](ref:notification-templates) 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:
@@ -265,10 +268,6 @@ Example of a custom payload template that includes variables:
 }
 ```

-{{< admonition type="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`).
@@ -62,6 +62,8 @@ To add an existing notification template to your contact point, complete the fol

 1. Click **Save contact point**.

+You can create custom notification templates using the **Enter custom message** tab. For reusable and consistent notifications, a best practice is to custom notification templates as described in the following section.
+
 ## Create a notification template and notification template group

 Create notification templates to customize notification messages and reuse them in contact points.
@@ -8,6 +8,7 @@ title: 'Custom webhook example'
 ---

 ```go
+{- /* Generates a pretty-printed JSON payload with alert group info and individual alerts metadata. */ -}}
 {{ define "webhook.custom.payload" -}}
  {{ coll.Dict
  "receiver" .Receiver