feat(webhooks): configurable UA and delivery status code

protobufs/livekit_analytics.proto

@@ -307,4 +307,5 @@ message WebhookInfo {
   int32 service_error_code = 20;
   string service_error = 21;
   string send_error = 22;
+  int32 http_status_code = 23; // HTTP response status code for the delivery attempt (0 if no response).
 }

webhook/consts.go

@@ -22,7 +22,17 @@ var (
 	ErrInvalidChecksum = errors.New("could not verify authenticity of message")
 )
 
-const authHeader = "Authorization"
+const (
+	authHeader        = "Authorization"
+	contentTypeHeader = "content-type"
+	userAgentHeader   = "User-Agent"
+)
+
+const (
+	// use a custom mime type to ensure signature is checked prior to parsing
+	ContentType      = "application/webhook+json"
+	DefaultUserAgent = "LiveKit"
+)
 
 const (
 	EventRoomStarted                  = "room_started"

webhook/filter.go

@@ -30,6 +30,12 @@ func (f *filter) SetFilter(params FilterParams) {
 	f.params = params
 }
 
+// IsAllowed reports whether event passes the include/exclude filter. IncludeEvents
+// takes precedence over ExcludeEvents; if neither is set, the event is allowed.
+func (p FilterParams) IsAllowed(event string) bool {
+	return newFilter(p).IsAllowed(event)
+}
+
 // IncludeEvents and ExcludeEvents are mutually exclusive; only one will be checked
 // if neither are set, the event will be allowed
 func (f *filter) IsAllowed(event string) bool {

webhook/notifier.go

@@ -186,6 +186,9 @@ type HTTPClientParams struct {
 	MaxRetries    int
 	ClientTimeout time.Duration
 	ForceIPv4     bool
+	// receivers pin WAF rules to this, so it must stay stable across releases
+	// defaults to DefaultUserAgent
+	UserAgent string
 }
 
 type FilterParams struct {

webhook/resource_url_notifier.go

@@ -117,6 +117,9 @@ func NewResourceURLNotifier(params ResourceURLNotifierParams) *ResourceURLNotifi
 	if params.Config.MaxDepth == 0 {
 		params.Config.MaxDepth = DefaultResourceURLNotifierConfig.MaxDepth
 	}
+	if params.UserAgent == "" {
+		params.UserAgent = DefaultUserAgent
+	}
 
 	rhc := retryablehttp.NewClient()
 	if params.RetryWaitMin > 0 {
@@ -374,8 +377,8 @@ func (r *ResourceURLNotifier) send(event *livekit.WebhookEvent, params *Resource
 		return err
 	}
 	req.Header.Set(authHeader, token)
-	// use a custom mime type to ensure signature is checked prior to parsing
-	req.Header.Set("content-type", "application/webhook+json")
+	req.Header.Set(contentTypeHeader, ContentType)
+	req.Header.Set(userAgentHeader, params.UserAgent)
 	res, err := r.client.Do(req)
 	if err != nil {
 		return err

webhook/url_notifier.go

@@ -79,6 +79,9 @@ func NewURLNotifier(params URLNotifierParams) *URLNotifier {
 	if params.Logger == nil {
 		params.Logger = logger.GetLogger()
 	}
+	if params.UserAgent == "" {
+		params.UserAgent = DefaultUserAgent
+	}
 
 	rhc := retryablehttp.NewClient()
 	if params.RetryWaitMin > 0 {
@@ -282,8 +285,8 @@ func (n *URLNotifier) send(event *livekit.WebhookEvent, params *URLNotifierParam
 		return err
 	}
 	r.Header.Set(authHeader, token)
-	// use a custom mime type to ensure signature is checked prior to parsing
-	r.Header.Set("content-type", "application/webhook+json")
+	r.Header.Set(contentTypeHeader, ContentType)
+	r.Header.Set(userAgentHeader, params.UserAgent)
 	res, err := n.client.Do(r)
 	if err != nil {
 		return err

webhook/webhook_test.go

@@ -74,6 +74,7 @@ func TestWebHook(t *testing.T) {
 
 			require.EqualValues(t, event, decodedEvent)
 			require.Equal(t, expectedUrl, r.URL.String())
+			require.Equal(t, DefaultUserAgent, r.UserAgent())
 		}
 		require.NoError(t, notifier.QueueNotify(context.Background(), event))
 		wg.Wait()
@@ -84,6 +85,35 @@ func TestWebHook(t *testing.T) {
 		wg.Wait()
 
 	})
+
+	t.Run("overridden user agent", func(t *testing.T) {
+		notifier := NewURLNotifier(URLNotifierParams{
+			URL:       testUrl,
+			APIKey:    testAPIKey,
+			APISecret: testAPISecret,
+			Config: URLNotifierConfig{
+				QueueSize: 20,
+			},
+			HTTPClientParams: HTTPClientParams{
+				UserAgent: "LiveKitCloud",
+			},
+		})
+		defer notifier.Stop(false)
+
+		ua := atomic.String{}
+		s.handler = func(w http.ResponseWriter, r *http.Request) {
+			ua.Store(r.UserAgent())
+		}
+		require.NoError(t, notifier.QueueNotify(context.Background(), &livekit.WebhookEvent{Event: EventRoomStarted}))
+		require.Eventually(
+			t,
+			func() bool {
+				return ua.Load() == "LiveKitCloud"
+			},
+			5*time.Second,
+			webhookCheckInterval,
+		)
+	})
 }
 
 func TestURLNotifierDropped(t *testing.T) {
@@ -395,11 +425,41 @@ func TestResourceWebHook(t *testing.T) {
 			require.NoError(t, err)
 
 			require.EqualValues(t, event, decodedEvent)
+			require.Equal(t, DefaultUserAgent, r.UserAgent())
 		}
 		require.NoError(t, resourceURLNotifier.QueueNotify(context.Background(), event))
 		wg.Wait()
 	})
 
+	t.Run("overridden user agent", func(t *testing.T) {
+		resourceURLNotifier := NewResourceURLNotifier(ResourceURLNotifierParams{
+			URL:       testUrl,
+			APIKey:    testAPIKey,
+			APISecret: testAPISecret,
+			Config: ResourceURLNotifierConfig{
+				MaxAge:   200 * time.Millisecond,
+				MaxDepth: 50,
+			},
+			HTTPClientParams: HTTPClientParams{
+				UserAgent: "LiveKitCloud",
+			},
+		})
+		defer resourceURLNotifier.Stop(false)
+
+		ua := atomic.String{}
+		s.handler = func(w http.ResponseWriter, r *http.Request) {
+			ua.Store(r.UserAgent())
+		}
+		require.NoError(t, resourceURLNotifier.QueueNotify(context.Background(), &livekit.WebhookEvent{Event: EventRoomStarted}))
+		require.Eventually(
+			t,
+			func() bool {
+				return ua.Load() == "LiveKitCloud"
+			},
+			5*time.Second,
+			webhookCheckInterval,
+		)
+	})
 }
 
 func TestResourceURLNotifierDropped(t *testing.T) {