feat(webhooks): type get_webhook_sample_payload return as TypedDict union

Parity with `tango-node`'s `WebhookSamplePayloadResponse` discriminated union.
The endpoint can return one of two response shapes depending on whether
`event_type` is supplied:

- Single-event: `{event_type, sample_delivery, signature_header, note}`
- All-events:   `{samples, usage, signature_header, note}`

Added `WebhookSampleDelivery`, `WebhookSamplePayloadSingleResponse`,
`WebhookSamplePayloadAllResponse`, and the union alias
`WebhookSamplePayloadResponse` as TypedDict classes (structural, no runtime
conversion). Exported from the top-level `tango` package and used as the
return annotation on `client.get_webhook_sample_payload()`. No behavior
change — just better static typing.

Verified against the live API:
- single (`alerts.contract.match`): returns 4 keys matching the Single shape
- all: returns 4 keys matching the All shape

All 285 unit tests still pass.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: infinityplusone

tango/__init__.py

@@ -24,6 +24,10 @@
     WebhookEndpoint,
     WebhookEventType,
     WebhookEventTypesResponse,
+    WebhookSampleDelivery,
+    WebhookSamplePayloadAllResponse,
+    WebhookSamplePayloadResponse,
+    WebhookSamplePayloadSingleResponse,
     WebhookTestDeliveryResult,
 )
 from .shapes import (
@@ -62,6 +66,10 @@
     "WebhookEndpoint",
     "WebhookEventType",
     "WebhookEventTypesResponse",
+    "WebhookSampleDelivery",
+    "WebhookSamplePayloadAllResponse",
+    "WebhookSamplePayloadResponse",
+    "WebhookSamplePayloadSingleResponse",
     "WebhookTestDeliveryResult",
     "ShapeParser",
     "ModelFactory",

tango/client.py

@@ -46,6 +46,7 @@
     WebhookEndpoint,
     WebhookEventType,
     WebhookEventTypesResponse,
+    WebhookSamplePayloadResponse,
     WebhookTestDeliveryResult,
 )
 from tango.shapes import (
@@ -2592,17 +2593,20 @@ def test_webhook_delivery(self, endpoint_id: str | None = None) -> WebhookTestDe
             test_payload=data.get("test_payload"),
         )
 
-    def get_webhook_sample_payload(self, event_type: str | None = None) -> dict[str, Any]:
+    def get_webhook_sample_payload(
+        self, event_type: str | None = None
+    ) -> WebhookSamplePayloadResponse:
         """
         Fetch Tango-shaped sample webhook deliveries.
 
-        - If event_type is provided, returns the single-event response.
-        - Otherwise returns a `samples` mapping for all supported event types.
+        - If ``event_type`` is provided, returns a :class:`WebhookSamplePayloadSingleResponse`.
+        - Otherwise returns a :class:`WebhookSamplePayloadAllResponse` with a ``samples``
+          mapping keyed by event type.
         """
         params: dict[str, Any] = {}
         if event_type:
             params["event_type"] = event_type
-        return self._get("/api/webhooks/endpoints/sample-payload/", params)
+        return self._get("/api/webhooks/endpoints/sample-payload/", params)  # type: ignore[return-value]
 
     # ============================================================================
     # Webhook Alerts (filter-based subscriptions)

tango/models.py

@@ -13,7 +13,7 @@
 from dataclasses import dataclass
 from datetime import date, datetime
 from decimal import Decimal
-from typing import Any, Final, Literal, TypeVar
+from typing import Any, Final, Literal, TypedDict, TypeVar
 
 T = TypeVar("T")
 
@@ -580,6 +580,30 @@ class WebhookEventTypesResponse:
     event_types: list[WebhookEventType]
 
 
+class WebhookSampleDelivery(TypedDict):
+    timestamp: str
+    events: list[dict[str, Any]]
+
+
+class WebhookSamplePayloadSingleResponse(TypedDict):
+    event_type: str
+    sample_delivery: WebhookSampleDelivery
+    signature_header: str
+    note: str
+
+
+class WebhookSamplePayloadAllResponse(TypedDict):
+    samples: dict[str, dict[str, Any]]
+    usage: str
+    signature_header: str
+    note: str
+
+
+WebhookSamplePayloadResponse = (
+    WebhookSamplePayloadSingleResponse | WebhookSamplePayloadAllResponse
+)
+
+
 @dataclass
 class WebhookEndpoint:
     id: str