Skip to content

armgit / Pulse

Public Imported from GitHub
0

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.

Make the copied webhook payload escape alert text

pulse-triage[bot]28b0b11837df
diff --git a/docs/WEBHOOKS.md b/docs/WEBHOOKS.md
index 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 Contract
These 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.md
index 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 Contract
These 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.ts
new file mode 100644
index 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.go
index 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"])
+}