From 470edab7061411ec8ec1b3a4c19e320c4ea6c671 Mon Sep 17 00:00:00 2001
From: "grafana-delivery-bot[bot]"
 <132647405+grafana-delivery-bot[bot]@users.noreply.github.com>
Date: Tue, 21 Oct 2025 18:49:20 +0000
Subject: [PATCH] [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 fb5c5411f86d6e258a9c22308fa0a707c20b9fee)

Co-authored-by: Pepe Cano <825430+ppcano@users.noreply.github.com>
Co-authored-by: Johnny Kartheiser <140559259+JohnnyK-Grafana@users.noreply.github.com>
---
 .../integrations/webhook-notifier.md              | 15 +++++++--------
 .../manage-notification-templates.md              |  2 ++
 .../shared/alerts/example-custom-json-payload.md  |  1 +
 3 files changed, 10 insertions(+), 8 deletions(-)

diff --git a/docs/sources/alerting/configure-notifications/manage-contact-points/integrations/webhook-notifier.md b/docs/sources/alerting/configure-notifications/manage-contact-points/integrations/webhook-notifier.md
index 2829b14e235..fdfbca1bb85 100644
--- a/docs/sources/alerting/configure-notifications/manage-contact-points/integrations/webhook-notifier.md
+++ b/docs/sources/alerting/configure-notifications/manage-contact-points/integrations/webhook-notifier.md
@@ -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`).
diff --git a/docs/sources/alerting/configure-notifications/template-notifications/manage-notification-templates.md b/docs/sources/alerting/configure-notifications/template-notifications/manage-notification-templates.md
index e449bb6ecff..c2ac3c8fffc 100644
--- a/docs/sources/alerting/configure-notifications/template-notifications/manage-notification-templates.md
+++ b/docs/sources/alerting/configure-notifications/template-notifications/manage-notification-templates.md
@@ -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.
diff --git a/docs/sources/shared/alerts/example-custom-json-payload.md b/docs/sources/shared/alerts/example-custom-json-payload.md
index cebf6183fa5..7182d59abf2 100644
--- a/docs/sources/shared/alerts/example-custom-json-payload.md
+++ b/docs/sources/shared/alerts/example-custom-json-payload.md
@@ -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