feat(integrations): Log masked custom webhook headers to request buffer

The webhook request buffer (surfaced in the custom integration debug API)
only recorded Sentry's own headers, so custom webhook_headers left no trace
there. Users debugging a failed delivery saw no sign their configured headers
were sent, which is confusing.

Buffer a masked version instead: custom header names are kept so the debug
view shows which headers were sent, but their values are replaced with
MASKED_VALUE so secrets are never persisted to the buffer. Sentry's own
headers stay in the clear and win name collisions, mirroring what is actually
sent on the wire.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

Author: billyvg

src/sentry/sentry_apps/api/serializers/app_platform_event.py

@@ -5,6 +5,7 @@
 from typing import Any, TypedDict
 from uuid import uuid4
 
+from sentry.sentry_apps.models.sentry_app import MASKED_VALUE
 from sentry.sentry_apps.models.sentry_app_installation import SentryAppInstallation
 from sentry.sentry_apps.services.app.model import RpcSentryAppInstallation
 from sentry.sentry_apps.utils.webhooks import SentryAppActionType, SentryAppResourceType
@@ -94,9 +95,6 @@ def body(self) -> str:
     def sentry_headers(self) -> dict[str, str]:
         """Headers Sentry sets on every webhook request.
 
-        These are the only headers recorded in the request buffer / debug UI:
-        custom webhook headers may carry secrets and must never be logged there.
-
         Cached so the Request-ID, timestamp, and signature are computed once and
         stay consistent between the sent request and the logged buffer entry.
         """
@@ -125,3 +123,23 @@ def headers(self) -> dict[str, str]:
         # Sentry's headers are merged last so they always win: a custom header
         # can never override the signature and spoof payload integrity.
         return {**self.custom_headers, **self.sentry_headers}
+
+    @property
+    def masked_custom_headers(self) -> dict[str, str]:
+        """Custom header names with their values replaced by MASKED_VALUE.
+
+        Custom header values may carry secrets (e.g. bearer tokens), so they are
+        never persisted to the request buffer. The names are kept so the debug UI
+        can show which custom headers were sent without leaking the values.
+        """
+        return {name: MASKED_VALUE for name in self.custom_headers}
+
+    @property
+    def loggable_headers(self) -> dict[str, str]:
+        """Headers safe to record in the request buffer / debug UI.
+
+        Sentry's own headers in the clear, plus custom headers with masked values.
+        Sentry's headers are merged last so the buffer mirrors the precedence of
+        what was actually sent (see ``headers``).
+        """
+        return {**self.masked_custom_headers, **self.sentry_headers}

src/sentry/utils/sentry_apps/webhooks.py

@@ -298,8 +298,9 @@ def send_and_save_webhook_request(
                 org_id=org_id,
                 event=event,
                 url=url,
-                # Only log Sentry's own headers; custom headers may contain secrets.
-                headers=app_platform_event.sentry_headers,
+                # Log Sentry's headers plus masked custom headers: custom header
+                # values may contain secrets and must never be persisted.
+                headers=app_platform_event.loggable_headers,
             )
             lifecycle.record_halt(e)
             # Re-raise the exception because some of these tasks might retry on the exception
@@ -330,8 +331,9 @@ def send_and_save_webhook_request(
             error_id=response.headers.get("Sentry-Hook-Error"),
             project_id=project_id,
             response=response,
-            # Only log Sentry's own headers; custom headers may contain secrets.
-            headers=app_platform_event.sentry_headers,
+            # Log Sentry's headers plus masked custom headers: custom header
+            # values may contain secrets and must never be persisted.
+            headers=app_platform_event.loggable_headers,
         )
 
         debug_logging_enabled = (

tests/sentry/sentry_apps/api/serializers/test_app_platform_event.py

@@ -4,7 +4,7 @@
 import orjson
 
 from sentry.sentry_apps.api.serializers.app_platform_event import AppPlatformEvent
-from sentry.sentry_apps.models.sentry_app import SentryApp
+from sentry.sentry_apps.models.sentry_app import MASKED_VALUE, SentryApp
 from sentry.sentry_apps.utils.webhooks import (
     InstallationActionType,
     IssueActionType,
@@ -128,13 +128,38 @@ def test_custom_headers_cannot_override_sentry_headers(self) -> None:
         assert result.headers["Content-Type"] == "application/json"
 
     def test_sentry_headers_exclude_custom_headers(self) -> None:
-        # sentry_headers is what gets logged to the request buffer / debug UI, so
-        # custom headers (which may contain secrets) must never appear there.
+        # sentry_headers carries only Sentry's own headers in the clear; custom
+        # headers (which may contain secrets) must never appear there unmasked.
         _, result = self._event_for_app_with_headers(["Authorization: Bearer secret"])
 
         assert "Authorization" not in result.sentry_headers
         assert result.headers["Authorization"] == "Bearer secret"
 
+    def test_loggable_headers_mask_custom_header_values(self) -> None:
+        # loggable_headers is what gets recorded in the request buffer / debug UI:
+        # custom header names are kept so users can confirm they were sent, but the
+        # values are masked so secrets never get persisted.
+        _, result = self._event_for_app_with_headers(
+            ["X-Custom: value", "Authorization: Bearer secret"]
+        )
+
+        loggable = result.loggable_headers
+        # Names are visible so the debug UI shows which custom headers were sent.
+        assert loggable["X-Custom"] == MASKED_VALUE
+        assert loggable["Authorization"] == MASKED_VALUE
+        # The real secret value is never recorded in the buffer.
+        assert "Bearer secret" not in loggable.values()
+        # Sentry's own headers stay in the clear so they remain useful for debugging.
+        assert loggable["Content-Type"] == "application/json"
+        assert loggable["Sentry-Hook-Signature"] == result.sentry_headers["Sentry-Hook-Signature"]
+
+    def test_loggable_headers_sentry_headers_win_collisions(self) -> None:
+        # A custom header that collides with a Sentry header must not shadow the real
+        # value in the buffer, mirroring the precedence of what was actually sent.
+        _, result = self._event_for_app_with_headers(["Content-Type: text/plain"])
+
+        assert result.loggable_headers["Content-Type"] == "application/json"
+
     def test_sentry_headers_are_stable_across_calls(self) -> None:
         # The Request-ID/timestamp logged to the buffer must match what was sent,
         # so sentry_headers is computed once per event rather than per access.

tests/sentry/utils/sentry_apps/test_webhooks.py

@@ -8,15 +8,17 @@
 
 from sentry.notifications.platform.service import NotificationService
 from sentry.sentry_apps.api.serializers.app_platform_event import AppPlatformEvent
+from sentry.sentry_apps.models.sentry_app import MASKED_VALUE
 from sentry.sentry_apps.utils.webhooks import IssueActionType, SentryAppResourceType
-from sentry.shared_integrations.exceptions import ApiHostError
+from sentry.shared_integrations.exceptions import ApiHostError, ClientError
 from sentry.testutils.asserts import assert_failure_metric
 from sentry.testutils.cases import TestCase
 from sentry.testutils.helpers.features import with_feature
 from sentry.testutils.helpers.options import override_options
 from sentry.testutils.silo import cell_silo_test
 from sentry.utils import redis
 from sentry.utils.circuit_breaker2 import CircuitBreaker
+from sentry.utils.sentry_apps import SentryAppWebhookRequestsBuffer
 from sentry.utils.sentry_apps.webhooks import WebhookTimeoutError, send_and_save_webhook_request
 
 
@@ -145,6 +147,44 @@ def test_http_error_response_records_success_and_raises(
 
         mock_record_success.assert_called_once()
 
+    @override_options(CIRCUIT_BREAKER_OPTIONS)
+    @patch("sentry.utils.sentry_apps.webhooks.safe_urlopen")
+    def test_error_response_buffers_masked_custom_headers(self, mock_safe_urlopen):
+        """A failed delivery records masked custom headers in the request buffer, so the
+        debug UI shows which custom headers were sent without persisting their secrets."""
+        sentry_app = self.create_sentry_app(
+            name="HeaderApp",
+            organization=self.organization,
+            webhook_url="https://example.com/webhook",
+            published=True,
+            webhook_headers=["Authorization: Bearer super-secret"],
+        )
+        install = self.create_sentry_app_installation(
+            organization=self.organization, slug=sentry_app.slug
+        )
+        event = AppPlatformEvent(
+            resource=SentryAppResourceType.ISSUE,
+            action=IssueActionType.CREATED,
+            install=install,
+            data={"test": "data"},
+        )
+        mock_safe_urlopen.return_value = _MockResponse(
+            {}, "{}", "", False, 401, _raise_status_false, None
+        )
+
+        with pytest.raises(ClientError):
+            send_and_save_webhook_request(sentry_app, event)
+
+        requests = SentryAppWebhookRequestsBuffer(sentry_app).get_requests(errors_only=True)
+        assert len(requests) == 1
+        headers = requests[0].get("request_headers")
+        assert headers is not None
+        # The custom header name is recorded but its value is masked.
+        assert headers["Authorization"] == MASKED_VALUE
+        assert "Bearer super-secret" not in headers.values()
+        # Sentry's own headers are still recorded in the clear.
+        assert headers["Content-Type"] == "application/json"
+
 
 @cell_silo_test
 class WebhookCircuitBreakerNotifyTest(TestCase):