From 9e4980320af5ccc6d284655757fa9a760121abee Mon Sep 17 00:00:00 2001 From: Pepe Cano <825430+ppcano@users.noreply.github.com> Date: Tue, 22 Apr 2025 22:14:50 +0200 Subject: [PATCH] docs(alerting): add JSON payload example to template examples list (#104282) --- .../integrations/webhook-notifier.md | 36 +---------- .../template-notifications/examples.md | 59 +++++++++++++++++++ .../alerts/example-custom-json-payload.md | 44 ++++++++++++++ 3 files changed, 104 insertions(+), 35 deletions(-) create mode 100644 docs/sources/shared/alerts/example-custom-json-payload.md 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 898b2ae98b5..1730fca9bb5 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 @@ -284,38 +284,4 @@ For detailed information about these and other template functions, refer to [not Example using JSON helper functions: -``` -{{ define "webhook.custom.payload" -}} - {{ coll.Dict - "receiver" .Receiver - "status" .Status - "alerts" (tmpl.Exec "webhook.custom.simple_alerts" .Alerts | data.JSON) - "groupLabels" .GroupLabels - "commonLabels" .CommonLabels - "commonAnnotations" .CommonAnnotations - "externalURL" .ExternalURL - "version" "1" - "orgId" (index .Alerts 0).OrgID - "truncatedAlerts" .TruncatedAlerts - "groupKey" .GroupKey - "state" (tmpl.Inline "{{ if eq .Status \"resolved\" }}ok{{ else }}alerting{{ end }}" . ) - "allVariables" .Vars - "title" (tmpl.Exec "default.title" . ) - "message" (tmpl.Exec "default.message" . ) - | data.ToJSONPretty " "}} -{{- end }} - -{{- /* Embed json templates in other json templates. */ -}} -{{ define "webhook.custom.simple_alerts" -}} - {{- $alerts := coll.Slice -}} - {{- range . -}} - {{ $alerts = coll.Append (coll.Dict - "status" .Status - "labels" .Labels - "startsAt" .StartsAt - "endsAt" .EndsAt - ) $alerts}} - {{- end -}} - {{- $alerts | data.ToJSON -}} -{{- end }} -``` +{{< docs/shared lookup="alerts/example-custom-json-payload.md" source="grafana" version="" >}} diff --git a/docs/sources/alerting/configure-notifications/template-notifications/examples.md b/docs/sources/alerting/configure-notifications/template-notifications/examples.md index d9ce3f780a0..7e916c5f60a 100644 --- a/docs/sources/alerting/configure-notifications/template-notifications/examples.md +++ b/docs/sources/alerting/configure-notifications/template-notifications/examples.md @@ -55,6 +55,11 @@ refs: destination: /docs/grafana//alerting/fundamentals/notifications/group-alert-notifications/ - pattern: /docs/grafana-cloud/ destination: /docs/grafana-cloud/alerting-and-irm/alerting/fundamentals/notifications/group-alert-notifications/ + custom-payload-webhook: + - pattern: /docs/grafana/ + destination: /docs/grafana//alerting/configure-notifications/manage-contact-points/integrations/webhook-notifier/#custom-payload + - pattern: /docs/grafana-cloud/ + destination: /docs/grafana-cloud/alerting-and-irm/alerting/configure-notifications/manage-contact-points/integrations/webhook-notifier/#custom-payload --- # Notification template examples @@ -402,3 +407,57 @@ Execute the template by passing the dot (`.`): ```template_output [FIRING:1, RESOLVED:1] api warning (sql_db) ``` + +## Custom JSON payload + +The [custom payload option](ref:custom-payload-webhook) in the webhook contact point allows you to customize the payload of webhook notifications using a custom template. + +The following example generates a custom JSON payload by executing other templates with `tmpl.Exec`, and using functions like `coll.Dict` and `data.ToJSON` to process and format JSON data. + +{{< docs/shared lookup="alerts/example-custom-json-payload.md" source="grafana" version="" >}} + +```template_output +{ + "alerts": [ + { + "endsAt": "0001-01-01T00:00:00Z", + "labels": { + "alertname": "InstanceDown", + "grafana_folder": "Test Folder", + "instance": "instance1" + }, + "startsAt": "2025-04-21T10:19:46.179Z", + "status": "firing" + }, + { + "endsAt": "2025-04-22T10:19:46.179Z", + "labels": { + "alertname": "CpuUsage", + "grafana_folder": "Test Folder", + "instance": "instance1" + }, + "startsAt": "2025-04-22T06:19:46.179Z", + "status": "resolved" + } + ], + "allVariables": {}, + "commonAnnotations": {}, + "commonLabels": { + "grafana_folder": "Test Folder", + "instance": "instance1" + }, + "externalURL": "http://localhost:3000/", + "groupKey": "", + "groupLabels": { + "group_label": "group_label_value" + }, + "message": "**Firing**\n\nValue: B=22, C=1\nLabels:\n - alertname = InstanceDown\n - grafana_folder = Test Folder\n - instance = instance1\nAnnotations:\n - summary = Instance instance1 has been down for more than 5 minutes\nSource: http://grafana.com/alerting/grafana/cdeqmlhvflz40f/view?orgId=1\nSilence: http://localhost:3000/alerting/silence/new?alertmanager=grafana\u0026matcher=alertname%3DInstanceDown\u0026matcher=grafana_folder%3DTest+Folder\u0026matcher=instance%3Dinstance1\u0026orgId=1\nDashboard: http://localhost:3000/d/dashboard_uid?from=1745227186179\u0026orgId=1\u0026to=1745317189058\nPanel: http://localhost:3000/d/dashboard_uid?from=1745227186179\u0026orgId=1\u0026to=1745317189058\u0026viewPanel=1\n\n\n**Resolved**\n\nValue: B=22, C=1\nLabels:\n - alertname = CpuUsage\n - grafana_folder = Test Folder\n - instance = instance1\nAnnotations:\n - summary = CPU usage above 90%\nSource: http://grafana.com/alerting/grafana/oZSMdGj7z/view?orgId=1\nSilence: http://localhost:3000/alerting/silence/new?alertmanager=grafana\u0026matcher=alertname%3DCpuUsage\u0026matcher=grafana_folder%3DTest+Folder\u0026matcher=instance%3Dinstance1\u0026orgId=1\nDashboard: http://localhost:3000/d/dashboard_uid?from=1745299186179\u0026orgId=1\u0026to=1745317186179\nPanel: http://localhost:3000/d/dashboard_uid?from=1745299186179\u0026orgId=1\u0026to=1745317186179\u0026viewPanel=1\n", + "orgId": 1, + "receiver": "TestReceiver", + "state": "alerting", + "status": "firing", + "title": "[FIRING:1, RESOLVED:1] group_label_value (Test Folder instance1)", + "truncatedAlerts": null, + "version": "1" +} +``` diff --git a/docs/sources/shared/alerts/example-custom-json-payload.md b/docs/sources/shared/alerts/example-custom-json-payload.md new file mode 100644 index 00000000000..cebf6183fa5 --- /dev/null +++ b/docs/sources/shared/alerts/example-custom-json-payload.md @@ -0,0 +1,44 @@ +--- +labels: + products: + - cloud + - enterprise + - oss +title: 'Custom webhook example' +--- + +```go +{{ define "webhook.custom.payload" -}} + {{ coll.Dict + "receiver" .Receiver + "status" .Status + "alerts" (tmpl.Exec "webhook.custom.simple_alerts" .Alerts | data.JSON) + "groupLabels" .GroupLabels + "commonLabels" .CommonLabels + "commonAnnotations" .CommonAnnotations + "externalURL" .ExternalURL + "version" "1" + "orgId" (index .Alerts 0).OrgID + "truncatedAlerts" .TruncatedAlerts + "groupKey" .GroupKey + "state" (tmpl.Inline "{{ if eq .Status \"resolved\" }}ok{{ else }}alerting{{ end }}" . ) + "allVariables" .Vars + "title" (tmpl.Exec "default.title" . ) + "message" (tmpl.Exec "default.message" . ) + | data.ToJSONPretty " "}} +{{- end }} + +{{- /* Embed json templates in other json templates. */ -}} +{{ define "webhook.custom.simple_alerts" -}} + {{- $alerts := coll.Slice -}} + {{- range . -}} + {{ $alerts = coll.Append (coll.Dict + "status" .Status + "labels" .Labels + "startsAt" .StartsAt + "endsAt" .EndsAt + ) $alerts}} + {{- end -}} + {{- $alerts | data.ToJSON -}} +{{- end }} +```