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.

Clarify the existing webhook correlation contract

pulse-triage[bot]c7bb48f0b4dc
diff --git a/docs/release-control/v6/internal/subsystems/notifications.md b/docs/release-control/v6/internal/subsystems/notifications.md
index 1e63866860..9081f935bf 100644
--- a/docs/release-control/v6/internal/subsystems/notifications.md
+++ b/docs/release-control/v6/internal/subsystems/notifications.md
@@ -493,9 +493,20 @@ through the canonical webhook transport must send `X-Pulse-Timestamp` and
`X-Pulse-Signature` (`v1=` + hex HMAC-SHA256 over `timestamp + "." + body`),
computed at the single request-construction choke point and set after custom
headers so user-provided header maps cannot shadow them. Alert deliveries also
-send `X-Pulse-Event-ID` (`alertID:event`) as the idempotency token; it must be
+send `X-Pulse-Event-ID` (`alertID:event`) as a legacy correlation token; it must be
stable across both transport-layer and queue-layer retries of the same alert
-occurrence. The management API must mask a configured signing secret on read
+occurrence. It omits occurrence start, severity and grouped membership and is
+not a unique incident or delivery identity; it is not covered by the HMAC.
+Receiver guidance must not prescribe permanent header-only deduplication.
+Normal queued templates expose every member through `.Alerts`, whose full-
+precision `StartTime` can distinguish later occurrences even when the primary
+RFC3339 start string has the same whole second. Correlate recovery with that
+occurrence and preserve severity updates and changed members. The existing
+wire format and retry stability remain unchanged. `webhook_guide_test.go`
+exercises copied templates through the actual signed sender over loopback for
+retry, escalation, recovery, recurrence, group changes and JSON escaping; it
+does not establish durable ticket actions or installed notification delivery.
+The management API must mask a configured signing secret on read
and preserve the stored secret when an update echoes the masked placeholder,
the same ownership rule it applies to header and custom-field secrets.
That same transport boundary also owns webhook request normalization. Rendered
diff --git a/scripts/tests/test_webhook_verification_docs.py b/scripts/tests/test_webhook_verification_docs.py
index 78fee09927..32b366e264 100644
--- a/scripts/tests/test_webhook_verification_docs.py
+++ b/scripts/tests/test_webhook_verification_docs.py
@@ -161,6 +161,9 @@ class WebhookVerificationDocsTest(unittest.TestCase):
self.assertNotIn("two-priority PSA mapping covers the full range", text)
self.assertIn('"info"', text)
self.assertIn("successful firing-delivery receipt", text)
+ contract = (ROOT / "docs/release-control/v6/internal/subsystems/notifications.md").read_text()
+ self.assertIn("as a legacy correlation token", contract)
+ self.assertIn("must not prescribe permanent header-only deduplication", contract)
if __name__ == "__main__":