chore(webhooks): Initial attempt to type AppPlatformEvent (#96376)

Christinarlong · web-flow · commit 873856f9ca79 · 2025-08-11T10:48:09.000-07:00
diff --git a/src/sentry/integrations/services/integration/impl.py b/src/sentry/integrations/services/integration/impl.py
@@ -51,6 +51,7 @@
 )
 from sentry.sentry_apps.models.sentry_app import SentryApp
 from sentry.sentry_apps.models.sentry_app_installation import SentryAppInstallation
+from sentry.sentry_apps.utils.webhooks import MetricAlertActionType, SentryAppResourceType
 from sentry.shared_integrations.exceptions import ApiError
 from sentry.utils import json
 from sentry.utils.sentry_apps import send_and_save_webhook_request
@@ -380,7 +381,9 @@ def send_incident_alert_notification(
     ) -> bool:
         try:
             new_status_str = INCIDENT_STATUS[IncidentStatus(new_status)].lower()
-            event = SentryAppEventType(f"metric_alert.{new_status_str}")
+            event = SentryAppEventType(
+                f"{SentryAppResourceType.METRIC_ALERT}.{MetricAlertActionType(new_status_str)}"
+            )
         except ValueError as e:
             sentry_sdk.capture_exception(e)
             return False
@@ -408,8 +411,8 @@ def send_incident_alert_notification(
                 return False
 
             app_platform_event = AppPlatformEvent(
-                resource="metric_alert",
-                action=new_status_str,
+                resource=SentryAppResourceType.METRIC_ALERT,
+                action=MetricAlertActionType(new_status_str),
                 install=install,
                 data=json.loads(incident_attachment_json),
             )
diff --git a/src/sentry/sentry_apps/api/parsers/sentry_app.py b/src/sentry/sentry_apps/api/parsers/sentry_app.py
@@ -9,11 +9,8 @@
 from sentry.integrations.models.integration_feature import Feature
 from sentry.models.apiscopes import ApiScopes
 from sentry.sentry_apps.api.parsers.schema import validate_ui_element_schema
-from sentry.sentry_apps.models.sentry_app import (
-    REQUIRED_EVENT_PERMISSIONS,
-    UUID_CHARS_IN_SLUG,
-    VALID_EVENT_RESOURCES,
-)
+from sentry.sentry_apps.models.sentry_app import REQUIRED_EVENT_PERMISSIONS, UUID_CHARS_IN_SLUG
+from sentry.sentry_apps.utils.webhooks import VALID_EVENT_RESOURCES
 
 
 @extend_schema_field(build_typed_list(OpenApiTypes.STR))
diff --git a/src/sentry/sentry_apps/api/serializers/app_platform_event.py b/src/sentry/sentry_apps/api/serializers/app_platform_event.py
@@ -1,49 +1,96 @@
+from collections.abc import Mapping
+from enum import StrEnum
 from time import time
+from typing import Any, TypedDict
 from uuid import uuid4
 
+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
+from sentry.users.models.user import User
+from sentry.users.services.user import RpcUser
 from sentry.utils import json
 
 
-class AppPlatformEvent:
+class AppPlatformEventActorType(StrEnum):
+    USER = "user"
+    APPLICATION = "application"
+
+
+class AppPlatformEventActor(TypedDict):
+    type: AppPlatformEventActorType
+    id: str | int
+    name: str
+
+
+class AppPlatformEventInstallation(TypedDict):
+    uuid: str
+
+
+class AppPlatformEventBody[T: Mapping[str, Any]](TypedDict):
+    action: SentryAppActionType
+    installation: AppPlatformEventInstallation
+    data: T
+    actor: AppPlatformEventActor
+
+
+class AppPlatformEvent[T: Mapping[str, Any]]():
     """
     This data structure encapsulates the payload sent to a SentryApp's webhook.
+
+    The data field is generic and should be typed with a TypedDict specified by the user.
     """
 
-    def __init__(self, resource, action, install, data, actor=None):
+    def __init__(
+        self,
+        resource: SentryAppResourceType,
+        action: SentryAppActionType,
+        install: RpcSentryAppInstallation | SentryAppInstallation,
+        data: T,
+        actor: RpcUser | User | None = None,
+    ):
         self.resource = resource
         self.action = action
         self.install = install
         self.data = data
         self.actor = actor
 
-    def get_actor(self):
+    def get_actor(self) -> AppPlatformEventActor:
         # when sentry auto assigns, auto resolves, etc.
         # or when an alert rule is triggered
         if not self.actor:
-            return {"type": "application", "id": "sentry", "name": "Sentry"}
+            return AppPlatformEventActor(
+                type=AppPlatformEventActorType.APPLICATION,
+                id="sentry",
+                name="Sentry",
+            )
 
         if self.actor.is_sentry_app:
-            return {
-                "type": "application",
-                "id": self.install.sentry_app.uuid,
-                "name": self.install.sentry_app.name,
-            }
+            return AppPlatformEventActor(
+                type=AppPlatformEventActorType.APPLICATION,
+                id=self.install.sentry_app.uuid,
+                name=self.install.sentry_app.name,
+            )
 
-        return {"type": "user", "id": self.actor.id, "name": self.actor.name}
+        return AppPlatformEventActor(
+            type=AppPlatformEventActorType.USER,
+            id=self.actor.id,
+            name=self.actor.name,
+        )
 
     @property
-    def body(self):
+    def body(self) -> str:
         return json.dumps(
-            {
-                "action": self.action,
-                "installation": {"uuid": self.install.uuid},
-                "data": self.data,
-                "actor": self.get_actor(),
-            },
+            AppPlatformEventBody(
+                action=self.action,
+                installation=AppPlatformEventInstallation(uuid=self.install.uuid),
+                data=self.data,
+                actor=self.get_actor(),
+            )
         )
 
     @property
-    def headers(self):
+    def headers(self) -> dict[str, str]:
         request_uuid = uuid4().hex
 
         return {
diff --git a/src/sentry/sentry_apps/api/serializers/sentry_app_installation.py b/src/sentry/sentry_apps/api/serializers/sentry_app_installation.py
@@ -1,7 +1,7 @@
 from __future__ import annotations
 
 from collections.abc import MutableMapping, Sequence
-from typing import Any
+from typing import Any, NotRequired, TypedDict
 
 from django.contrib.auth.models import AnonymousUser
 
@@ -14,6 +14,24 @@
 from sentry.users.services.user import RpcUser
 
 
+class SentryAppInstallationAppResult(TypedDict):
+    uuid: str
+    slug: str
+
+
+class SentryAppInstallationOrganizationResult(TypedDict):
+    slug: str
+    id: int
+
+
+class SentryAppInstallationResult(TypedDict):
+    app: SentryAppInstallationAppResult
+    organization: SentryAppInstallationOrganizationResult
+    uuid: str
+    status: str
+    code: NotRequired[str]
+
+
 @register(SentryAppInstallation)
 class SentryAppInstallationSerializer(Serializer):
     def get_attrs(
@@ -41,9 +59,11 @@ def get_attrs(
             }
         return result
 
-    def serialize(self, obj, attrs, user: User | RpcUser | AnonymousUser, **kwargs):
+    def serialize(
+        self, obj, attrs, user: User | RpcUser | AnonymousUser, **kwargs
+    ) -> SentryAppInstallationResult:
         access = kwargs.get("access")
-        data = {
+        data: SentryAppInstallationResult = {
             "app": {"uuid": attrs["sentry_app"].uuid, "slug": attrs["sentry_app"].slug},
             "organization": {"slug": attrs["organization"].slug, "id": attrs["organization"].id},
             "uuid": obj.uuid,
diff --git a/src/sentry/sentry_apps/installations.py b/src/sentry/sentry_apps/installations.py
@@ -3,6 +3,7 @@
 import dataclasses
 import datetime
 from functools import cached_property
+from typing import TypedDict
 
 from django.db import router, transaction
 from django.http.request import HttpRequest
@@ -15,6 +16,7 @@
 from sentry.models.apitoken import ApiToken
 from sentry.sentry_apps.api.serializers.app_platform_event import AppPlatformEvent
 from sentry.sentry_apps.api.serializers.sentry_app_installation import (
+    SentryAppInstallationResult,
     SentryAppInstallationSerializer,
 )
 from sentry.sentry_apps.metrics import (
@@ -28,6 +30,7 @@
 from sentry.sentry_apps.services.hook import hook_service
 from sentry.sentry_apps.tasks.sentry_apps import installation_webhook
 from sentry.sentry_apps.utils.errors import SentryAppSentryError
+from sentry.sentry_apps.utils.webhooks import InstallationActionType, SentryAppResourceType
 from sentry.users.models.user import User
 from sentry.users.services.user.model import RpcUser
 from sentry.utils import metrics
@@ -190,6 +193,10 @@ def sentry_app(self) -> SentryApp:
         return SentryApp.objects.get(slug=self.slug)
 
 
+class SentryAppInstallationWebhookData(TypedDict):
+    installation: SentryAppInstallationResult
+
+
 @dataclasses.dataclass
 class SentryAppInstallationNotifier:
     sentry_app_installation: SentryAppInstallation
@@ -205,19 +212,19 @@ def run(self) -> None:
         send_and_save_webhook_request(self.sentry_app, self.request)
 
     @property
-    def request(self) -> AppPlatformEvent:
+    def request(self) -> AppPlatformEvent[SentryAppInstallationWebhookData]:
         data = serialize(
             self.sentry_app_installation,
             user=self.user,
             serializer=SentryAppInstallationSerializer(),
             is_webhook=True,
         )
 
-        return AppPlatformEvent(
-            resource="installation",
-            action=self.action,
+        return AppPlatformEvent[SentryAppInstallationWebhookData](
+            resource=SentryAppResourceType.INSTALLATION,
+            action=InstallationActionType(self.action),
             install=self.sentry_app_installation,
-            data={"installation": data},
+            data=SentryAppInstallationWebhookData(installation=data),
             actor=self.user,
         )
 
diff --git a/src/sentry/sentry_apps/logic.py b/src/sentry/sentry_apps/logic.py
@@ -33,7 +33,6 @@
     SentryAppInteractionType,
 )
 from sentry.sentry_apps.models.sentry_app import (
-    EVENT_EXPANSION,
     REQUIRED_EVENT_PERMISSIONS,
     UUID_CHARS_IN_SLUG,
     SentryApp,
@@ -42,6 +41,7 @@
 from sentry.sentry_apps.models.sentry_app_component import SentryAppComponent
 from sentry.sentry_apps.models.sentry_app_installation import SentryAppInstallation
 from sentry.sentry_apps.tasks.sentry_apps import create_or_update_service_hooks_for_sentry_app
+from sentry.sentry_apps.utils.webhooks import EVENT_EXPANSION, SentryAppResourceType
 from sentry.users.models.user import User
 from sentry.users.services.user.model import RpcUser
 from sentry.utils.sentry_apps.service_hook_manager import (
@@ -71,14 +71,18 @@ def expand_events(rolled_up_events: list[str]) -> list[str]:
     """
     Convert a list of rolled up events ('issue', etc) into a list of raw event
     types ('issue.created', etc.)
+
+    Can also be given a list of event types (e.g. ['issue.created', 'issue.resolved'])
     """
-    return sorted(
-        {
-            translated
-            for event in rolled_up_events
-            for translated in EVENT_EXPANSION.get(event, [event])
-        }
-    )
+
+    expanded_events = []
+    for event in rolled_up_events:
+        if event in EVENT_EXPANSION:
+            expanded_events.extend(EVENT_EXPANSION.get(SentryAppResourceType(event), [event]))
+        else:
+            expanded_events.append(event)
+
+    return sorted(set(expanded_events))
 
 
 # TODO(schew2381): Delete this method after staff is GA'd and the options are removed
diff --git a/src/sentry/sentry_apps/models/sentry_app.py b/src/sentry/sentry_apps/models/sentry_app.py
@@ -31,29 +31,10 @@
 from sentry.hybridcloud.models.outbox import ControlOutbox, outbox_context
 from sentry.hybridcloud.outbox.category import OutboxCategory, OutboxScope
 from sentry.models.apiscopes import HasApiScopes
+from sentry.sentry_apps.utils.webhooks import EVENT_EXPANSION
 from sentry.types.region import find_all_region_names, find_regions_for_sentry_app
 from sentry.utils import metrics
 
-# When a developer selects to receive "<Resource> Webhooks" it really means
-# listening to a list of specific events. This is a mapping of what those
-# specific events are for each resource.
-EVENT_EXPANSION = {
-    "issue": [
-        "issue.assigned",
-        "issue.created",
-        "issue.ignored",
-        "issue.resolved",
-        "issue.unresolved",
-    ],
-    "error": ["error.created"],
-    "comment": ["comment.created", "comment.deleted", "comment.updated"],
-}
-
-# We present Webhook Subscriptions per-resource (Issue, Project, etc.), not
-# per-event-type (issue.created, project.deleted, etc.). These are valid
-# resources a Sentry App may subscribe to.
-VALID_EVENT_RESOURCES = ("issue", "error", "comment")
-
 REQUIRED_EVENT_PERMISSIONS = {
     "issue": "event:read",
     "error": "event:read",
diff --git a/src/sentry/sentry_apps/tasks/sentry_apps.py b/src/sentry/sentry_apps/tasks/sentry_apps.py
@@ -49,6 +49,7 @@
 )
 from sentry.sentry_apps.services.hook.service import hook_service
 from sentry.sentry_apps.utils.errors import SentryAppSentryError
+from sentry.sentry_apps.utils.webhooks import IssueAlertActionType, SentryAppResourceType
 from sentry.shared_integrations.exceptions import ApiHostError, ApiTimeoutError, ClientError
 from sentry.silo.base import SiloMode
 from sentry.tasks.base import instrumented_task, retry
@@ -257,7 +258,10 @@ def send_alert_webhook_v2(
             data[additional_payload_key] = additional_payload
 
         request_data = AppPlatformEvent(
-            resource="event_alert", action="triggered", install=install, data=data
+            resource=SentryAppResourceType.EVENT_ALERT,
+            action=IssueAlertActionType.TRIGGERED,
+            install=install,
+            data=data,
         )
 
     send_and_save_webhook_request(sentry_app, request_data)
diff --git a/src/sentry/sentry_apps/utils/webhooks.py b/src/sentry/sentry_apps/utils/webhooks.py
diff --git a/src/sentry/utils/sentry_apps/webhooks.py b/src/sentry/utils/sentry_apps/webhooks.py
diff --git a/tests/sentry/sentry_apps/api/serializers/test_app_platform_event.py b/tests/sentry/sentry_apps/api/serializers/test_app_platform_event.py
diff --git a/tests/sentry/sentry_apps/services/test_hook_service.py b/tests/sentry/sentry_apps/services/test_hook_service.py
