From fcb3feb772d24adf622b472520a1fbe895275d6d Mon Sep 17 00:00:00 2001
From: Prem Pillai <238277+cloud-on-prem@users.noreply.github.com>
Date: Tue, 11 Aug 2026 08:04:53 +1000
Subject: [PATCH] docs(relay): clarify usage webhook boundary

Signed-off-by: Prem Pillai <238277+cloud-on-prem@users.noreply.github.com>
---
 .env.example                             | 6 +++++-
 crates/buzz-relay/src/usage_analytics.rs | 7 ++++---
 2 files changed, 9 insertions(+), 4 deletions(-)

diff --git a/.env.example b/.env.example
index f3ccd0a09e..10bb6e778e 100644
--- a/.env.example
+++ b/.env.example
@@ -133,13 +133,17 @@ RUST_LOG=buzz_relay=debug,buzz_datastore=info,buzz_db=debug,buzz_auth=debug,buzz
 # Usage analytics webhook
 # -----------------------------------------------------------------------------
 # Disabled by default. When configured, the relay posts one small JSON event
-# after each newly persisted kind:9 message. The payload contains the author's
+# after each newly persisted client-submitted stream message (Nostr kind 9).
+# Relay-authored automation is excluded. The payload contains the author's
 # public key, the opaque community UUID, and relay acceptance time; it never
 # includes message content or tags.
 # The public key is a stable pseudonym and may be personal data.
 #
 # Remote endpoints must use HTTPS. HTTP is accepted only for localhost or a
 # loopback IP so the webhook can be exercised during local development.
+# The relay sends no authentication header. Protect the endpoint with
+# deployment-level access controls, such as a loopback sidecar or private
+# network gateway; do not expose it as an unauthenticated public URL.
 # BUZZ_USAGE_ANALYTICS_ENDPOINT=https://analytics.example.com/events
 
 # -----------------------------------------------------------------------------
diff --git a/crates/buzz-relay/src/usage_analytics.rs b/crates/buzz-relay/src/usage_analytics.rs
index 9f35e9af6b..f926052ff7 100644
--- a/crates/buzz-relay/src/usage_analytics.rs
+++ b/crates/buzz-relay/src/usage_analytics.rs
@@ -1,9 +1,10 @@
 //! Best-effort usage-event delivery for relay operators.
 //!
 //! The exporter is deliberately small: it emits one privacy-minimal JSON
-//! object for each newly persisted kind:9 message. Delivery never blocks event
-//! ingestion; a bounded queue drops analytics work when its single worker
-//! cannot keep up.
+//! object for each newly persisted client-submitted stream message (Nostr kind
+//! 9). Relay-authored automation is intentionally excluded. Delivery never
+//! blocks event ingestion; a bounded queue drops analytics work when its single
+//! worker cannot keep up.
 
 use std::time::Duration;