feat(api): add safety warning and deactivation webhook events (openai#3908)

## Summary

Adds typed webhook payloads for safety warnings and deactivations.

## Changes

- Parse safety.warning_issued and safety.deactivation_issued through the
existing webhook unwrap methods.
- Expose each event's safety case ID in data.id.

Author: jbeckwith-oai

.castiron.stats.yml

@@ -1,8 +1,8 @@
 schema_version: 1
-generation_id: 4e2c0a68-f552-4057-9398-0656631a643d
-openapi_spec_hash: b81e20e8186e5f45afc36ecb4ceb3b33
-openapi_transformed_spec_hash: 73682ea454f2f3c2bde8466c223eb434
+generation_id: df936b0c-3a74-4407-aff0-23ee0aa5a051
+openapi_spec_hash: 83d739d1f34f3c6641c60fb43f882cb9
+openapi_transformed_spec_hash: 11ef1888efd4aab54eed55a63ac4c9cd
 config_hash: ba291299a0f8e738664099a7d7741f24
-codegen_sha: 91a42dc9d1a7ce0aae0e5202636b0e6470190813
-codegen_hash: ee7a457167dd360a7d59f207be427c7c12db2bae58ac9967fbf8a46b2757cf9a
-public_codegen_sha: 367700a19c7975b8e616abcd58e1b7c1a574b106
+codegen_sha: c5827dc664f987f9b5c708746cb2f5365c3d5755
+codegen_hash: 76e577a907d602c7d7f45ba7ecb9b19db4db064f8196f59ec372b7d496ae5f67
+public_codegen_sha: 842234b163ff84a841598aba8ac8569f69204051

api_reference/openapi.transformed.yml

@@ -30653,6 +30653,20 @@ webhooks:
       responses:
         '200':
           description: Return any 2xx status code to acknowledge receipt. A 410 Gone response also stops retries; other non-2xx responses are retried.
+  safety_deactivation_issued:
+    post:
+      description: |
+        Sent when a deactivation is issued for a safety identifier in your organization.
+        Retrieve the case details with `GET /v1/safety/cases/{id}` using `data.id`.
+      requestBody:
+        description: The event payload sent by the API.
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/WebhookSafetyDeactivationIssued'
+      responses:
+        '200':
+          description: Return any 2xx status code to acknowledge receipt. A 410 Gone response also stops retries; other non-2xx responses are retried.
   safety_org_alert_created:
     post:
       description: |
@@ -30669,6 +30683,20 @@ webhooks:
       responses:
         '200':
           description: Return any 2xx status code to acknowledge receipt. A 410 Gone response also stops retries; other non-2xx responses are retried.
+  safety_warning_issued:
+    post:
+      description: |
+        Sent when a warning is issued for a safety identifier in your organization.
+        Retrieve the case details with `GET /v1/safety/cases/{id}` using `data.id`.
+      requestBody:
+        description: The event payload sent by the API.
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/WebhookSafetyWarningIssued'
+      responses:
+        '200':
+          description: Return any 2xx status code to acknowledge receipt. A 410 Gone response also stops retries; other non-2xx responses are retried.
 components:
   schemas:
     AddUploadPartRequest:
@@ -66166,6 +66194,56 @@ components:
             "type": "safety.alert.created",
             "data": {"id": "alert_0123456789abcdef0123456789abcdef"}
           }
+    WebhookSafetyDeactivationIssued:
+      type: object
+      title: safety.deactivation_issued
+      description: Sent when a deactivation is issued for a safety identifier in your organization.
+      required:
+      - id
+      - object
+      - created_at
+      - type
+      - data
+      properties:
+        id:
+          type: string
+          description: The unique ID of the webhook event.
+        object:
+          type: string
+          enum:
+          - event
+          x-stainless-const: true
+          description: Always `event`.
+        created_at:
+          type: integer
+          format: unixtime
+          description: The Unix timestamp in seconds when the event was created.
+        type:
+          type: string
+          enum:
+          - safety.deactivation_issued
+          x-stainless-const: true
+          description: Always `safety.deactivation_issued`.
+        data:
+          type: object
+          additionalProperties: false
+          required:
+          - id
+          properties:
+            id:
+              type: string
+              description: The safety case ID to pass to `GET /v1/safety/cases/{id}`.
+      x-oaiMeta:
+        name: safety.deactivation_issued
+        group: webhook-events
+        example: |
+          {
+            "id": "evt_123",
+            "object": "event",
+            "created_at": 1787659200,
+            "type": "safety.deactivation_issued",
+            "data": {"id": "C-abc123"}
+          }
     WebhookSafetyOrgAlertCreated:
       type: object
       title: safety.org_alert.created
@@ -66217,6 +66295,56 @@ components:
             "type": "safety.org_alert.created",
             "data": {"id": "alert_0123456789abcdef0123456789abcdef"}
           }
+    WebhookSafetyWarningIssued:
+      type: object
+      title: safety.warning_issued
+      description: Sent when a warning is issued for a safety identifier in your organization.
+      required:
+      - id
+      - object
+      - created_at
+      - type
+      - data
+      properties:
+        id:
+          type: string
+          description: The unique ID of the webhook event.
+        object:
+          type: string
+          enum:
+          - event
+          x-stainless-const: true
+          description: Always `event`.
+        created_at:
+          type: integer
+          format: unixtime
+          description: The Unix timestamp in seconds when the event was created.
+        type:
+          type: string
+          enum:
+          - safety.warning_issued
+          x-stainless-const: true
+          description: Always `safety.warning_issued`.
+        data:
+          type: object
+          additionalProperties: false
+          required:
+          - id
+          properties:
+            id:
+              type: string
+              description: The safety case ID to pass to `GET /v1/safety/cases/{id}`.
+      x-oaiMeta:
+        name: safety.warning_issued
+        group: webhook-events
+        example: |
+          {
+            "id": "evt_123",
+            "object": "event",
+            "created_at": 1787659200,
+            "type": "safety.warning_issued",
+            "data": {"id": "C-abc123"}
+          }
     ModerationInputType:
       type: string
       enum:
@@ -96519,6 +96647,12 @@ x-oaiMeta:
     - type: object
       key: WebhookLiveTransportIncoming
       path: <auto>
+    - type: object
+      key: WebhookSafetyWarningIssued
+      path: <auto>
+    - type: object
+      key: WebhookSafetyDeactivationIssued
+      path: <auto>
     - type: object
       key: WebhookSafetyAlertCreated
       path: <auto>

src/openai/resources/webhooks/api.md

@@ -23,7 +23,9 @@ from openai.types.webhooks import (
     ResponseFailedWebhookEvent,
     ResponseIncompleteWebhookEvent,
     SafetyAlertCreatedWebhookEvent,
+    SafetyDeactivationIssuedWebhookEvent,
     SafetyOrgAlertCreatedWebhookEvent,
+    SafetyWarningIssuedWebhookEvent,
     UnwrapWebhookEvent,
     WebhookEndpoint,
     WebhookEndpointList,

src/openai/types/webhooks/__init__.py

@@ -29,6 +29,7 @@
 from .response_completed_webhook_event import ResponseCompletedWebhookEvent as ResponseCompletedWebhookEvent
 from .response_incomplete_webhook_event import ResponseIncompleteWebhookEvent as ResponseIncompleteWebhookEvent
 from .safety_alert_created_webhook_event import SafetyAlertCreatedWebhookEvent as SafetyAlertCreatedWebhookEvent
+from .safety_warning_issued_webhook_event import SafetyWarningIssuedWebhookEvent as SafetyWarningIssuedWebhookEvent
 from .fine_tuning_job_failed_webhook_event import FineTuningJobFailedWebhookEvent as FineTuningJobFailedWebhookEvent
 from .realtime_call_incoming_webhook_event import RealtimeCallIncomingWebhookEvent as RealtimeCallIncomingWebhookEvent
 from .live_transport_incoming_webhook_event import (
@@ -46,3 +47,6 @@
 from .safety_identifier_blocked_webhook_event import (
     SafetyIdentifierBlockedWebhookEvent as SafetyIdentifierBlockedWebhookEvent,
 )
+from .safety_deactivation_issued_webhook_event import (
+    SafetyDeactivationIssuedWebhookEvent as SafetyDeactivationIssuedWebhookEvent,
+)

src/openai/types/webhooks/safety_deactivation_issued_webhook_event.py

@@ -0,0 +1,32 @@
+# File generated from our OpenAPI spec by Castiron. See CONTRIBUTING.md for details.
+
+from typing_extensions import Literal
+
+from ..._models import BaseModel
+
+__all__ = ["SafetyDeactivationIssuedWebhookEvent", "Data"]
+
+
+class Data(BaseModel):
+    id: str
+    """The safety case ID to pass to `GET /v1/safety/cases/{id}`."""
+
+
+class SafetyDeactivationIssuedWebhookEvent(BaseModel):
+    """
+    Sent when a deactivation is issued for a safety identifier in your organization.
+    """
+
+    id: str
+    """The unique ID of the webhook event."""
+
+    created_at: int
+    """The Unix timestamp in seconds when the event was created."""
+
+    data: Data
+
+    object: Literal["event"]
+    """Always `event`."""
+
+    type: Literal["safety.deactivation_issued"]
+    """Always `safety.deactivation_issued`."""

src/openai/types/webhooks/safety_warning_issued_webhook_event.py

@@ -0,0 +1,30 @@
+# File generated from our OpenAPI spec by Castiron. See CONTRIBUTING.md for details.
+
+from typing_extensions import Literal
+
+from ..._models import BaseModel
+
+__all__ = ["SafetyWarningIssuedWebhookEvent", "Data"]
+
+
+class Data(BaseModel):
+    id: str
+    """The safety case ID to pass to `GET /v1/safety/cases/{id}`."""
+
+
+class SafetyWarningIssuedWebhookEvent(BaseModel):
+    """Sent when a warning is issued for a safety identifier in your organization."""
+
+    id: str
+    """The unique ID of the webhook event."""
+
+    created_at: int
+    """The Unix timestamp in seconds when the event was created."""
+
+    data: Data
+
+    object: Literal["event"]
+    """Always `event`."""
+
+    type: Literal["safety.warning_issued"]
+    """Always `safety.warning_issued`."""

src/openai/types/webhooks/unwrap_webhook_event.py

@@ -17,12 +17,14 @@
 from .response_completed_webhook_event import ResponseCompletedWebhookEvent
 from .response_incomplete_webhook_event import ResponseIncompleteWebhookEvent
 from .safety_alert_created_webhook_event import SafetyAlertCreatedWebhookEvent
+from .safety_warning_issued_webhook_event import SafetyWarningIssuedWebhookEvent
 from .fine_tuning_job_failed_webhook_event import FineTuningJobFailedWebhookEvent
 from .realtime_call_incoming_webhook_event import RealtimeCallIncomingWebhookEvent
 from .live_transport_incoming_webhook_event import LiveTransportIncomingWebhookEvent
 from .safety_org_alert_created_webhook_event import SafetyOrgAlertCreatedWebhookEvent
 from .fine_tuning_job_cancelled_webhook_event import FineTuningJobCancelledWebhookEvent
 from .fine_tuning_job_succeeded_webhook_event import FineTuningJobSucceededWebhookEvent
+from .safety_deactivation_issued_webhook_event import SafetyDeactivationIssuedWebhookEvent
 
 __all__ = ["UnwrapWebhookEvent"]
 
@@ -46,7 +48,9 @@
         ResponseFailedWebhookEvent,
         ResponseIncompleteWebhookEvent,
         SafetyAlertCreatedWebhookEvent,
+        SafetyDeactivationIssuedWebhookEvent,
         SafetyOrgAlertCreatedWebhookEvent,
+        SafetyWarningIssuedWebhookEvent,
     ],
     PropertyInfo(discriminator="type"),
 ]

tests/lib/test_webhooks.py

@@ -10,7 +10,11 @@
 
 import openai
 from openai._exceptions import InvalidWebhookSignatureError
-from openai.types.webhooks import UnwrapWebhookEvent
+from openai.types.webhooks import (
+    UnwrapWebhookEvent,
+    SafetyWarningIssuedWebhookEvent,
+    SafetyDeactivationIssuedWebhookEvent,
+)
 
 base_url = os.environ.get("TEST_API_BASE_URL", "http://127.0.0.1:4010")
 
@@ -22,6 +26,10 @@
 TEST_SIGNATURE = "v1,gUAg4R2hWouRZqRQG4uJypNS8YK885G838+EHb4nKBY="
 SIP_EVENT_TYPES = ["live.call.incoming", "live.transport.incoming", "realtime.call.incoming"]
 SIP_MEDIA_SECURITY_VALUES = [None, "rtp", "srtp", "future_media_security"]
+SAFETY_EVENT_TYPES = {
+    "safety.warning_issued": SafetyWarningIssuedWebhookEvent,
+    "safety.deactivation_issued": SafetyDeactivationIssuedWebhookEvent,
+}
 
 
 def create_test_headers(
@@ -66,9 +74,49 @@ def assert_sip_event(event: UnwrapWebhookEvent, event_type: str, media_security:
     assert event.to_dict() == json.loads(payload)
 
 
+def create_safety_test_payload(event_type: str) -> tuple[str, dict[str, str]]:
+    payload = json.dumps(
+        {
+            "id": "evt_safety_test",
+            "object": "event",
+            "created_at": TEST_TIMESTAMP,
+            "type": event_type,
+            "data": {"id": "case_test"},
+        }
+    )
+    signed_payload = f"{TEST_WEBHOOK_ID}.{TEST_TIMESTAMP}.{payload}".encode()
+    signature = base64.b64encode(
+        hmac.new(base64.b64decode(TEST_SECRET.removeprefix("whsec_")), signed_payload, "sha256").digest()
+    ).decode()
+    return payload, create_test_headers(signature=f"v1,{signature}")
+
+
+def assert_safety_event(event: UnwrapWebhookEvent, event_type: str, payload: str) -> None:
+    assert isinstance(event, SAFETY_EVENT_TYPES[event_type])
+    assert event.type == "safety.warning_issued" or event.type == "safety.deactivation_issued"
+    assert event.type == event_type
+    assert event.data.id == "case_test"
+    assert event.to_dict() == json.loads(payload)
+
+
 class TestWebhooks:
     parametrize = pytest.mark.parametrize("client", [False, True], indirect=True, ids=["loose", "strict"])
 
+    @mock.patch("time.time", mock.MagicMock(return_value=TEST_TIMESTAMP))
+    @parametrize
+    @pytest.mark.parametrize("event_type", SAFETY_EVENT_TYPES)
+    def test_unwrap_safety_events(self, client: openai.OpenAI, event_type: str) -> None:
+        payload, headers = create_safety_test_payload(event_type)
+        event = client.webhooks.unwrap(payload, headers, secret=TEST_SECRET)
+        assert_safety_event(event, event_type, payload)
+
+        for tampered_payload in [payload.replace("case_test", "case_tampered"), "{"]:
+            with pytest.raises(InvalidWebhookSignatureError, match="The given webhook signature does not match"):
+                client.webhooks.unwrap(tampered_payload, headers, secret=TEST_SECRET)
+
+        with pytest.raises(InvalidWebhookSignatureError, match="The given webhook signature does not match"):
+            client.webhooks.unwrap(payload, headers, secret="wrong_safety_webhook_secret")
+
     @mock.patch("time.time", mock.MagicMock(return_value=TEST_TIMESTAMP))
     @parametrize
     @pytest.mark.parametrize("event_type", SIP_EVENT_TYPES)
@@ -220,6 +268,21 @@ class TestAsyncWebhooks:
         "async_client", [False, True, {"http_client": "aiohttp"}], indirect=True, ids=["loose", "strict", "aiohttp"]
     )
 
+    @mock.patch("time.time", mock.MagicMock(return_value=TEST_TIMESTAMP))
+    @parametrize
+    @pytest.mark.parametrize("event_type", SAFETY_EVENT_TYPES)
+    async def test_unwrap_safety_events(self, async_client: openai.AsyncOpenAI, event_type: str) -> None:
+        payload, headers = create_safety_test_payload(event_type)
+        event = async_client.webhooks.unwrap(payload, headers, secret=TEST_SECRET)
+        assert_safety_event(event, event_type, payload)
+
+        for tampered_payload in [payload.replace("case_test", "case_tampered"), "{"]:
+            with pytest.raises(InvalidWebhookSignatureError, match="The given webhook signature does not match"):
+                async_client.webhooks.unwrap(tampered_payload, headers, secret=TEST_SECRET)
+
+        with pytest.raises(InvalidWebhookSignatureError, match="The given webhook signature does not match"):
+            async_client.webhooks.unwrap(payload, headers, secret="wrong_safety_webhook_secret")
+
     @mock.patch("time.time", mock.MagicMock(return_value=TEST_TIMESTAMP))
     @parametrize
     @pytest.mark.parametrize("event_type", SIP_EVENT_TYPES)