Real-time monitoring dashboard for Proxmox VE, PBS, Docker, Kubernetes, TrueNAS and vSphere. Self-hosted, with alerts for failed backups, full disks, unhealthy containers and offline nodes.
Go aialertsdashboarddockerdocker-monitoringgohomelabinfrastructure-monitoringkubernetesmonitoringmspproxmoxproxmox-backup-serverproxmox-mail-gatewayproxmox-veself-hostedtruenastypescriptvspherewebhooks
Make the copied webhook payload escape alert text
pulse-triage[bot]28b0b11837df
diff --git a/docs/WEBHOOKS.md b/docs/WEBHOOKS.mdindex 146334b3ab..126cfe1eaf 100644--- a/docs/WEBHOOKS.md+++ b/docs/WEBHOOKS.md@@ -63,11 +63,20 @@ For generic webhooks, use Go templates to format the JSON payload.**Example Payload:**```json{- "text": "Alert: {{.Level}} - {{.Message}}",+ "text": "Alert: {{.Level | jsonString}} - {{.Message | jsonString}}","value": {{.Value}}}```+Keep `jsonString` inside the JSON string's quotes. Leave numeric `.Value`+unquoted. A simple test message can work without escaping while a real alert+containing quotes, backslashes or newlines produces invalid or altered JSON.++This minimal payload is a text summary, not a structured record of every+group member or its firing/recovery identity. Use the [full PSA payload](#sample-psa-payloads)+when a receiver needs those fields; do not use the summary alone to deduplicate+incidents or close tickets.+## 📦 Delivery ContractThese fields and behaviors are stable; ticket-routing integrations can rely on them.diff --git a/frontend-modern/public/docs/WEBHOOKS.md b/frontend-modern/public/docs/WEBHOOKS.mdindex 146334b3ab..126cfe1eaf 100644--- a/frontend-modern/public/docs/WEBHOOKS.md+++ b/frontend-modern/public/docs/WEBHOOKS.md@@ -63,11 +63,20 @@ For generic webhooks, use Go templates to format the JSON payload.**Example Payload:**```json{- "text": "Alert: {{.Level}} - {{.Message}}",+ "text": "Alert: {{.Level | jsonString}} - {{.Message | jsonString}}","value": {{.Value}}}```+Keep `jsonString` inside the JSON string's quotes. Leave numeric `.Value`+unquoted. A simple test message can work without escaping while a real alert+containing quotes, backslashes or newlines produces invalid or altered JSON.++This minimal payload is a text summary, not a structured record of every+group member or its firing/recovery identity. Use the [full PSA payload](#sample-psa-payloads)+when a receiver needs those fields; do not use the summary alone to deduplicate+incidents or close tickets.+## 📦 Delivery ContractThese fields and behaviors are stable; ticket-routing integrations can rely on them.diff --git a/frontend-modern/src/features/docs/__tests__/webhookExampleGuide.test.ts b/frontend-modern/src/features/docs/__tests__/webhookExampleGuide.test.tsnew file mode 100644index 0000000000..453145f297--- /dev/null+++ b/frontend-modern/src/features/docs/__tests__/webhookExampleGuide.test.ts@@ -0,0 +1,47 @@+import { readFileSync } from 'node:fs';+import path from 'node:path';+import { fileURLToPath } from 'node:url';+import { describe, expect, it } from 'vitest';+import { renderDocMarkdown } from '../docMarkdown';++const root = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '../../../../..');+const guide = readFileSync(path.join(root, 'docs/WEBHOOKS.md'), 'utf8');++function render(): HTMLElement {+ const article = document.createElement('article');+ article.innerHTML = renderDocMarkdown(guide, 'WEBHOOKS');+ return article;+}++describe('copyable webhook example', () => {+ it('ships and renders the escaped JSON template without changing copied source', () => {+ expect(readFileSync(path.join(root, 'frontend-modern/public/docs/WEBHOOKS.md'), 'utf8')).toBe(+ guide,+ );+ const example = guide.split('**Example Payload:**')[1]?.match(/```json\n([\s\S]*?)\n```/)?.[1];+ expect(example).toContain(+ '"text": "Alert: {{.Level | jsonString}} - {{.Message | jsonString}}"',+ );+ expect(example).toContain('"value": {{.Value}}');+ expect([...render().querySelectorAll('pre code')].map((block) => block.textContent)).toContain(+ `${example}\n`,+ );+ });++ it('explains the simple-test blind spot and links the existing structured group example', () => {+ const article = render();+ const text = article.textContent?.replace(/\s+/g, ' ');+ expect(text).toContain("Keep jsonString inside the JSON string's quotes");+ expect(text).toContain('Leave numeric .Value unquoted');+ expect(text).toContain('A simple test message can work without escaping while a real alert');+ expect(text).toContain('invalid or altered JSON');+ expect(text).toContain('not a structured record of every group member');+ expect(text).toContain(+ 'do not use the summary alone to deduplicate incidents or close tickets',+ );+ expect(article.querySelector('a[href="#sample-psa-payloads"]')?.textContent).toBe(+ 'full PSA payload',+ );+ expect(article.querySelector('#sample-psa-payloads')).not.toBeNull();+ });+});diff --git a/internal/notifications/webhook_guide_test.go b/internal/notifications/webhook_guide_test.goindex 37a27878f8..f70b837caf 100644--- a/internal/notifications/webhook_guide_test.go+++ b/internal/notifications/webhook_guide_test.go@@ -191,3 +191,53 @@ func TestWebhookGuideShortTemplateEscapesStrings(t *testing.T) {require.Equal(t, "warning: "+alert.ResourceName+" "+alert.Message, payload["summary"])require.Equal(t, alert.StartTime.Format(time.RFC3339), payload["startedAt"])}++func webhookGuideExamplePayload(t *testing.T) string {+ t.Helper()+ sections := strings.SplitN(webhookGuide(t), "**Example Payload:**", 2)+ require.Len(t, sections, 2)+ block := regexp.MustCompile("(?s)```json\\n(.*?)\\n```").FindStringSubmatch(sections[1])+ require.Len(t, block, 2)+ return block[1]+}++func TestWebhookGuideExamplePayloadEscapesAlertText(t *testing.T) {+ for _, message := range []struct {+ name, text string+ value float64+ }{+ {"simple-test", "A simple test notification", 0},+ {"quoted-name", `Resource "synthetic-host" is unavailable`, 95.25},+ {"backslash-path", `Synthetic path C:\backup\reports`, 12.5},+ {"multiline", "Synthetic first line\nsecond line\r\nthird\tcolumn", 1},+ {"unicode", "Synthetic é host — 警告", 0.0286},+ {"member-injection", `Synthetic text", "injected": true, "other": "value`, 99},+ } {+ t.Run(message.name, func(t *testing.T) {+ manager, webhook, requests := webhookGuideSender(t, webhookGuideExamplePayload(t))+ alert := &alerts.Alert{ID: "synthetic-example", ResourceName: "synthetic-host",+ Level: alerts.AlertLevelWarning, Message: message.text, Value: message.value}+ require.NoError(t, manager.sendGroupedWebhook(webhook, []*alerts.Alert{alert}))+ request, _ := webhookGuideRead(t, requests)+ var payload map[string]interface{}+ require.NoError(t, json.Unmarshal([]byte(request.body), &payload))+ require.Len(t, payload, 2, "alert text must not add JSON members")+ require.Equal(t, "Alert: warning - "+message.text, payload["text"])+ require.Equal(t, message.value, payload["value"], "numbers must remain numeric")+ })+ }+}++func TestWebhookGuideExamplePayloadEscapesRecoveryText(t *testing.T) {+ manager, webhook, requests := webhookGuideSender(t, webhookGuideExamplePayload(t))+ alert := &alerts.Alert{ID: "synthetic-example", ResourceName: "synthetic \"host\"\nwith \\ path",+ Node: "synthetic-node", Level: alerts.AlertLevelWarning, Value: 0,+ StartTime: time.Date(2026, 10, 6, 4, 0, 0, 0, time.UTC)}+ require.NoError(t, manager.sendResolvedWebhook(webhook, []*alerts.Alert{alert}, alert.StartTime.Add(time.Minute)))+ request, _ := webhookGuideRead(t, requests)+ var payload map[string]interface{}+ require.NoError(t, json.Unmarshal([]byte(request.body), &payload))+ require.Len(t, payload, 2)+ require.Equal(t, "Alert: warning - "+alert.ResourceName+" on "+alert.Node+" is now healthy", payload["text"])+ require.Equal(t, float64(0), payload["value"])+}