feat(seer): Seer webhooks + generic webhook broadcaster (#96222)

Implements a generic webhook broadcaster in
`broadcast_webhooks_for_organization` in
`src/sentry/sentry_apps/webhooks.py` and calls it via Seer RPC.

We'll fully pass the event type and payload to it from Seer and have
Seer handle what's actually sent there. We also register the webhook
event types:
```
"seer.root_cause_started",
"seer.root_cause_completed",
"seer.solution_started",
"seer.solution_completed",
"seer.coding_started",
"seer.coding_completed",
"seer.pr_created",
```
and the Seer RPC function is guarded by a feature flag
`organizations:seer-webhooks`

---------

Co-authored-by: getsantry[bot] <66042841+getsantry[bot]@users.noreply.github.com>

Author: jennmueng

src/sentry/features/temporary.py

@@ -398,6 +398,8 @@ def register_temporary_features(manager: FeatureManager):
     manager.add("organizations:insights-mobile-screens-module", OrganizationFeature, FeatureHandlerStrategy.FLAGPOLE, api_expose=True)
     # Removes performance landing page from sidebar and updates transaction summary breadcrumbs for insights
     manager.add("organizations:insights-performance-landing-removal", OrganizationFeature, FeatureHandlerStrategy.FLAGPOLE, api_expose=True)
+    # Seer Webhooks to be sent and listened to
+    manager.add("organizations:seer-webhooks", OrganizationFeature, FeatureHandlerStrategy.FLAGPOLE, api_expose=True)
     # Enable new SentryApp webhook request endpoint
     manager.add("organizations:sentry-app-webhook-requests", OrganizationFeature, FeatureHandlerStrategy.FLAGPOLE, api_expose=False)
     # Enable standalone span ingestion

src/sentry/seer/endpoints/seer_rpc.py

@@ -35,7 +35,7 @@
 from sentry_protos.snuba.v1.trace_item_attribute_pb2 import AttributeKey, AttributeValue, StrArray
 from sentry_protos.snuba.v1.trace_item_filter_pb2 import ComparisonFilter, TraceItemFilter
 
-from sentry import options
+from sentry import features, options
 from sentry.api.api_owners import ApiOwner
 from sentry.api.api_publish_status import ApiPublishStatus
 from sentry.api.authentication import AuthenticationSiloLimit, StandardAuthentication
@@ -52,7 +52,7 @@
 from sentry.integrations.github_enterprise.integration import GitHubEnterpriseIntegration
 from sentry.integrations.services.integration import integration_service
 from sentry.integrations.types import IntegrationProviderSlug
-from sentry.models.organization import Organization
+from sentry.models.organization import Organization, OrganizationStatus
 from sentry.models.repository import Repository
 from sentry.search.eap.resolver import SearchResolver
 from sentry.search.eap.spans.definitions import SPAN_DEFINITIONS
@@ -75,6 +75,7 @@
     get_latest_issue_event,
 )
 from sentry.seer.seer_setup import get_seer_org_acknowledgement
+from sentry.sentry_apps.tasks.sentry_apps import broadcast_webhooks_for_organization
 from sentry.silo.base import SiloMode
 from sentry.snuba.referrer import Referrer
 from sentry.utils import snuba_rpc
@@ -602,6 +603,56 @@ def get_github_enterprise_integration_config(
     }
 
 
+def send_seer_webhook(*, event_name: str, organization_id: int, payload: dict) -> dict:
+    """
+    Send a seer webhook event for an organization.
+
+    Args:
+        event_name: The sub-name of seer event (e.g., "root_cause_started")
+        organization_id: The ID of the organization to send the webhook for
+        payload: The webhook payload data
+
+    Returns:
+        dict: Status of the webhook sending operation
+    """
+    # Validate event_name by constructing the full event type and checking if it's valid
+    from sentry.sentry_apps.metrics import SentryAppEventType
+
+    event_type = f"seer.{event_name}"
+    try:
+        SentryAppEventType(event_type)
+    except ValueError:
+        logger.exception(
+            "seer.webhook_invalid_event_type",
+            extra={"event_type": event_type},
+        )
+        return {"success": False, "error": f"Invalid event type: {event_type}"}
+
+    # Handle organization lookup safely
+    try:
+        organization = Organization.objects.get(
+            id=organization_id, status=OrganizationStatus.ACTIVE
+        )
+    except Organization.DoesNotExist:
+        logger.exception(
+            "seer.webhook_organization_not_found_or_not_active",
+            extra={"organization_id": organization_id},
+        )
+        return {"success": False, "error": "Organization not found or not active"}
+
+    if not features.has("organizations:seer-webhooks", organization):
+        return {"success": False, "error": "Seer webhooks are not enabled for this organization"}
+
+    broadcast_webhooks_for_organization.delay(
+        resource_name="seer",
+        event_name=event_name,
+        organization_id=organization_id,
+        payload=payload,
+    )
+
+    return {"success": True}
+
+
 seer_method_registry: dict[str, Callable[..., dict[str, Any]]] = {
     "get_organization_slug": get_organization_slug,
     "get_sentry_organization_ids": get_sentry_organization_ids,
@@ -621,6 +672,7 @@ def get_github_enterprise_integration_config(
     "get_profiles_for_trace": rpc_get_profiles_for_trace,
     "get_issues_for_transaction": rpc_get_issues_for_transaction,
     "get_github_enterprise_integration_config": get_github_enterprise_integration_config,
+    "send_seer_webhook": send_seer_webhook,
 }
 
 

src/sentry/sentry_apps/metrics.py

@@ -136,3 +136,12 @@ class SentryAppEventType(StrEnum):
     WEBHOOK_UPDATE = "webhook_update"
     INSTALLATION_CREATE = "install_create"
     INSTALLATION_WEBHOOK_UPDATE = "installation_webhook_update"
+
+    # seer webhooks
+    SEER_ROOT_CAUSE_STARTED = "seer.root_cause_started"
+    SEER_ROOT_CAUSE_COMPLETED = "seer.root_cause_completed"
+    SEER_SOLUTION_STARTED = "seer.solution_started"
+    SEER_SOLUTION_COMPLETED = "seer.solution_completed"
+    SEER_CODING_STARTED = "seer.coding_started"
+    SEER_CODING_COMPLETED = "seer.coding_completed"
+    SEER_PR_CREATED = "seer.pr_created"

src/sentry/sentry_apps/models/sentry_app.py

@@ -38,6 +38,7 @@
 REQUIRED_EVENT_PERMISSIONS = {
     "issue": "event:read",
     "error": "event:read",
+    "seer": "event:read",
     "project": "project:read",
     "member": "member:read",
     "organization": "org:read",

src/sentry/sentry_apps/tasks/__init__.py

@@ -1,4 +1,5 @@
 from .sentry_apps import (
+    broadcast_webhooks_for_organization,
     build_comment_webhook,
     clear_region_cache,
     create_or_update_service_hooks_for_sentry_app,
@@ -13,15 +14,16 @@
 from .service_hooks import process_service_hook
 
 __all__ = (
+    "broadcast_webhooks_for_organization",
     "build_comment_webhook",
     "clear_region_cache",
     "create_or_update_service_hooks_for_sentry_app",
     "installation_webhook",
     "process_resource_change_bound",
-    "send_resource_change_webhook",
-    "workflow_notification",
     "process_service_hook",
+    "regenerate_service_hooks_for_installation",
     "send_alert_webhook",
     "send_alert_webhook_v2",
-    "regenerate_service_hooks_for_installation",
+    "send_resource_change_webhook",
+    "workflow_notification",
 )

src/sentry/sentry_apps/tasks/sentry_apps.py

@@ -892,3 +892,91 @@ def regenerate_service_hooks_for_installation(
                 events=events,
                 url=webhook_url,
             )
+
+
+@instrumented_task(
+    name="sentry.sentry_apps.tasks.sentry_apps.broadcast_webhooks_for_organization",
+    taskworker_config=TaskworkerConfig(
+        namespace=sentryapp_tasks,
+        retry=Retry(
+            times=3,
+            delay=60 * 5,
+        ),
+        processing_deadline_duration=30,
+    ),
+    **TASK_OPTIONS,
+)
+def broadcast_webhooks_for_organization(
+    *,
+    resource_name: str,
+    event_name: str,
+    organization_id: int,
+    payload: dict[str, Any],
+    **kwargs: Any,
+) -> None:
+    """
+    Send a webhook event to all relevant installations for an organization.
+
+    Args:
+        resource_name: The resource name (e.g., "seer", "issue", "error")
+        event_name: The event name (e.g., "root_cause_started", "created")
+        organization_id: The ID of the organization to send webhooks for
+        payload: The webhook payload data
+
+    Returns:
+        dict: Status of the webhook sending operation including success status,
+              message, and error details if applicable
+    """
+    # Construct full event type for validation
+    event_type = f"{resource_name}.{event_name}"
+
+    # Validate event type by checking if it's a valid SentryAppEventType
+    try:
+        SentryAppEventType(event_type)
+    except ValueError:
+        logger.exception("sentry_app.webhook_invalid_event_type", extra={"event_type": event_type})
+
+        raise SentryAppSentryError(
+            message=f"Invalid event type: {event_type}",
+        )
+
+    with SentryAppInteractionEvent(
+        operation_type=SentryAppInteractionType.PREPARE_WEBHOOK,
+        event_type=event_type,
+    ).capture():
+        # Get installations for this organization
+        installations = app_service.installations_for_organization(organization_id=organization_id)
+
+        # Filter for installations that subscribe to the event category
+        from sentry.sentry_apps.logic import consolidate_events
+
+        relevant_installations = [
+            installation
+            for installation in installations
+            if resource_name in consolidate_events(installation.sentry_app.events)
+        ]
+
+        if not relevant_installations:
+            logger.error(
+                "sentry_app.webhook_no_installations_subscribed",
+                extra={
+                    "resource_name": resource_name,
+                    "organization_id": organization_id,
+                },
+            )
+            return
+
+        # Send the webhook to each relevant installation
+        for installation in relevant_installations:
+            if installation:
+                send_resource_change_webhook.delay(installation.id, event_type, payload)
+
+                logger.info(
+                    "sentry_app.webhook_queued",
+                    extra={"event_type": event_type, "installation_id": installation.id},
+                )
+            else:
+                logger.error(
+                    "sentry_app.webhook_no_installation",
+                    extra={"event_type": event_type, "organization_id": organization_id},
+                )

src/sentry/sentry_apps/utils/webhooks.py

@@ -40,6 +40,16 @@ class InstallationActionType(SentryAppActionType):
     DELETED = "deleted"
 
 
+class SeerActionType(SentryAppActionType):
+    ROOT_CAUSE_STARTED = "root_cause_started"
+    ROOT_CAUSE_COMPLETED = "root_cause_completed"
+    SOLUTION_STARTED = "solution_started"
+    SOLUTION_COMPLETED = "solution_completed"
+    CODING_STARTED = "coding_started"
+    CODING_COMPLETED = "coding_completed"
+    PR_CREATED = "pr_created"
+
+
 class SentryAppResourceType(StrEnum):
 
     @staticmethod
@@ -57,6 +67,7 @@ def map_sentry_app_webhook_events(
     COMMENT = "comment"
     INSTALLATION = "installation"
     METRIC_ALERT = "metric_alert"
+    SEER = "seer"
 
     # Represents an issue alert resource
     EVENT_ALERT = "event_alert"
@@ -75,6 +86,9 @@ def map_sentry_app_webhook_events(
     SentryAppResourceType.COMMENT: SentryAppResourceType.map_sentry_app_webhook_events(
         SentryAppResourceType.COMMENT.value, CommentActionType
     ),
+    SentryAppResourceType.SEER: SentryAppResourceType.map_sentry_app_webhook_events(
+        SentryAppResourceType.SEER.value, SeerActionType
+    ),
 }
 # We present Webhook Subscriptions per-resource (Issue, Project, etc.), not
 # per-event-type (issue.created, project.deleted, etc.). These are valid

tests/sentry/seer/endpoints/test_seer_rpc.py

@@ -593,3 +593,123 @@ def test_get_sentry_organization_ids_multiple_orgs_same_repo(self) -> None:
         )
 
         assert result == {"org_ids": [self.organization.id, org2.id]}
+
+    def test_send_seer_webhook_invalid_event_name(self) -> None:
+        """Test that send_seer_webhook returns error for invalid event names"""
+        from sentry.seer.endpoints.seer_rpc import send_seer_webhook
+
+        # Test with an invalid event name
+        result = send_seer_webhook(
+            event_name="invalid_event_name",
+            organization_id=self.organization.id,
+            payload={"test": "data"},
+        )
+
+        assert result == {
+            "success": False,
+            "error": "Invalid event type: seer.invalid_event_name",
+        }
+
+    def test_send_seer_webhook_organization_does_not_exist(self) -> None:
+        """Test that send_seer_webhook returns error for non-existent organization"""
+        from sentry.seer.endpoints.seer_rpc import send_seer_webhook
+
+        # Test with a non-existent organization ID
+        result = send_seer_webhook(
+            event_name="root_cause_started",
+            organization_id=99999,
+            payload={"test": "data"},
+        )
+
+        assert result == {
+            "success": False,
+            "error": "Organization not found or not active",
+        }
+
+    def test_send_seer_webhook_organization_inactive(self) -> None:
+        """Test that send_seer_webhook returns error for inactive organization"""
+        from sentry.models.organization import OrganizationStatus
+        from sentry.seer.endpoints.seer_rpc import send_seer_webhook
+
+        # Create an inactive organization
+        inactive_org = self.create_organization(status=OrganizationStatus.PENDING_DELETION)
+
+        result = send_seer_webhook(
+            event_name="root_cause_started",
+            organization_id=inactive_org.id,
+            payload={"test": "data"},
+        )
+
+        assert result == {
+            "success": False,
+            "error": "Organization not found or not active",
+        }
+
+    @patch("sentry.features.has")
+    def test_send_seer_webhook_feature_disabled(self, mock_features_has) -> None:
+        """Test that send_seer_webhook returns error when feature is disabled"""
+        from sentry.seer.endpoints.seer_rpc import send_seer_webhook
+
+        mock_features_has.return_value = False
+
+        result = send_seer_webhook(
+            event_name="root_cause_started",
+            organization_id=self.organization.id,
+            payload={"test": "data"},
+        )
+
+        assert result == {
+            "success": False,
+            "error": "Seer webhooks are not enabled for this organization",
+        }
+        mock_features_has.assert_called_once_with("organizations:seer-webhooks", self.organization)
+
+    @patch("sentry.features.has")
+    @patch("sentry.sentry_apps.tasks.sentry_apps.broadcast_webhooks_for_organization.delay")
+    def test_send_seer_webhook_success(self, mock_delay, mock_features_has) -> None:
+        """Test that send_seer_webhook successfully enqueues webhook when all conditions are met"""
+        from sentry.seer.endpoints.seer_rpc import send_seer_webhook
+
+        mock_features_has.return_value = True
+
+        result = send_seer_webhook(
+            event_name="root_cause_started",
+            organization_id=self.organization.id,
+            payload={"test": "data"},
+        )
+
+        assert result == {"success": True}
+        mock_features_has.assert_called_once_with("organizations:seer-webhooks", self.organization)
+        mock_delay.assert_called_once_with(
+            resource_name="seer",
+            event_name="root_cause_started",
+            organization_id=self.organization.id,
+            payload={"test": "data"},
+        )
+
+    @patch("sentry.features.has")
+    @patch("sentry.sentry_apps.tasks.sentry_apps.broadcast_webhooks_for_organization.delay")
+    def test_send_seer_webhook_all_valid_event_names(self, mock_delay, mock_features_has) -> None:
+        """Test that send_seer_webhook works with all valid seer event names"""
+        from sentry.seer.endpoints.seer_rpc import send_seer_webhook
+        from sentry.sentry_apps.metrics import SentryAppEventType
+
+        mock_features_has.return_value = True
+
+        # Get all seer event types
+        seer_events = [
+            event_type.value.split(".", 1)[1]  # Remove "seer." prefix
+            for event_type in SentryAppEventType
+            if event_type.value.startswith("seer.")
+        ]
+
+        for event_name in seer_events:
+            result = send_seer_webhook(
+                event_name=event_name,
+                organization_id=self.organization.id,
+                payload={"test": "data"},
+            )
+            assert result == {"success": True}
+
+        # Verify that the task was called for each valid event
+        assert mock_delay.call_count == len(seer_events)