1# Safety enforcement notifications
2
3> For the complete documentation index, see [llms.txt](/llms.txt). Markdown versions of documentation pages are available by appending `.md` to the page URL.
4
5Use safety webhooks and the Safety Case Read API to connect OpenAI enforcement notices to your team's workflows. For example, when a warning arrives, your application can retrieve its case details, identify the affected user, and create an internal review ticket.
6
7## When to use this
8
9Use this integration to:
10
11- Route warning and deactivation notices to your trust and safety, security, or support team.
12- Add case details to an investigation or support ticket.
13- Associate a notice with a user through your application's safety-identifier mapping.
14
15The steps in this guide use a warning to illustrate the workflow. You can use the same integration for deactivation notices.
16
17## How it works
18
19Safety webhooks notify your application that a notice was issued. The Safety Case Read API provides the details for that notice.
20
21| Event | Notice |
22| ---------------------------- | ------------------------------------------------------------ |
23| `safety.warning_issued` | A warning for a safety identifier in your organization. |
24| `safety.deactivation_issued` | A deactivation for a safety identifier in your organization. |
25
26Each event contains a case ID. Use it with `GET /v1/safety/cases/{id}` to retrieve the safety identifier, notice type, case creation timestamp, and available policy reason.
27
28These organization-level notifications are separate from project-level [misalignment alerts](https://developers.openai.com/api/docs/guides/safety-checks/misalignment-monitoring#receive-project-safety-alerts). Retrieving a case does not change or reverse the enforcement. The API returns case metadata, not the underlying conversation or a full investigation report.
29
30## Integrate with your application
31
32Start by configuring an organization-level webhook and a key for case lookups. Then connect the notifications to your review workflow.
33
34### 1. Configure your webhook and API key
35
36Use a stable [safety identifier](https://developers.openai.com/api/docs/guides/safety-best-practices#implement-safety-identifiers) for each user, and keep your application's mapping from that identifier to the user. Avoid including personal information in the identifier.
37
38Open your [organization webhook settings](https://platform.openai.com/settings/organization/webhooks) and select **Create**. Enter your receiver's HTTPS URL and subscribe to `safety.warning_issued` and `safety.deactivation_issued`. Save the signing secret securely so your receiver can verify incoming events. These events use an organization endpoint, not a project endpoint.
39
40Your account needs `api.webhooks.read` and `organization.read` to view organization webhooks, plus `api.webhooks.write` and `organization.write` to create them. See [Permissions](https://developers.openai.com/api/docs/guides/rbac) for role configuration.
41
42For case lookups, configure an API key for the same organization with **Restricted** permissions and set **Safety** to **Read** (`api.safety.read`). The API key authenticates case lookups; it is separate from the webhook signing secret.
43
44### 2. Receive and verify the event
45
46A warning notification has this structure. The IDs are illustrative:
47
48```json
49{
50 "id": "evt_example",
51 "object": "event",
52 "created_at": 1787659200,
53 "type": "safety.warning_issued",
54 "data": {
55 "id": "C-example"
56 }
57}
58```
59
60Verify the signature before processing the event. Save the verified event for processing, return a successful `2xx` response promptly, and retrieve the case in a background worker. See the Webhooks guide for [signature verification](https://developers.openai.com/api/docs/guides/webhooks#verifying-webhook-signatures) and [acknowledgments, retries, and duplicate deliveries](https://developers.openai.com/api/docs/guides/webhooks#handling-webhook-requests-on-a-server).
61
62The event's `id` identifies the webhook event. Its `data.id` identifies the safety case to retrieve.
63
64### 3. Retrieve the case
65
66Set `OPENAI_API_KEY` to your API key. Replace `C-example` with `data.id` from the verified event:
67
68```bash
69curl "https://api.openai.com/v1/safety/cases/C-example" \
70 -H "Authorization: Bearer ${OPENAI_API_KEY}"
71```
72
73A successful lookup returns HTTP `200` and a case object. For example:
74
75```json
76{
77 "id": "C-example",
78 "object": "safety.case",
79 "created_at": 1787659100,
80 "entity_identifier": "safety-id-example",
81 "reason": "cyber_abuse",
82 "notice": {
83 "type": "warning"
84 }
85}
86```
87
88Use `entity_identifier` to find the affected user in your application. The `reason` can be `null`; continue processing the notice when no reason is available.
89
90The case creation timestamp is not necessarily the event timestamp or the time of an individual request. See the [Safety Case API reference](https://developers.openai.com/api/reference/resources/safety/subresources/cases/methods/retrieve) for field definitions.
91
92### 4. Create a review ticket
93
94Add the case ID, notice type, safety identifier, case creation timestamp, and available policy reason to your internal ticket. Link the matching user record so your team can investigate using its own application records. If you cannot find a matching user, preserve the case details and flag the missing mapping for review.
95
96Make ticket creation safe to retry. Follow the [webhook deduplication guidance](https://developers.openai.com/api/docs/guides/webhooks#handling-webhook-requests-on-a-server) so repeated deliveries do not create duplicate tickets. Retries of your own background processing should also reuse the existing ticket.
97
98If an agent helps with triage, limit its access to the records it needs and keep customer-facing actions subject to your existing approval controls.
99
100## Confirm it's working
101
102For a real event and an accessible case in your organization, check that:
103
1041. Your receiver verifies the signature and returns a successful acknowledgment.
1052. The lookup returns HTTP `200`, with a case `id` matching the event's `data.id`.
1063. Your application identifies the expected user or flags a missing mapping.
1074. One review ticket contains the available case details. Reprocessing the event does not create another ticket.
108
109Before receiving a real notice, test your processing logic with local example events and mocked case responses. Include both notice types, a `null` reason, a missing user mapping, and duplicate deliveries. Test signature verification separately, including rejection of invalid signatures; keep it enabled on your production receiver.
110
111The example IDs on this page are not retrievable cases. Mocked tests validate your processing logic, not live delivery or API permissions. Do not trigger an actual enforcement to test your integration. An absence of enforcement notifications alone does not indicate a broken integration.
112
113## Troubleshoot
114
115| Symptom | What to check |
116| ----------------------------------------- | -------------------------------------------------------------------------------------------------------- |
117| Signature verification fails | Check the signing secret and preserve the raw request body as described in the Webhooks guide. |
118| Lookup returns `401` | Check that the API key is present and valid. |
119| Lookup returns `403` | Check that the key has the `api.safety.read` permission. |
120| Lookup returns `404` | Use `data.id`, not the event ID. Check that the case belongs to the key's organization. |
121| Lookup returns `429` or a transient `5xx` | Retry with backoff and a bounded retry policy. Preserve the event for later processing or investigation. |
122| A ticket is created more than once | Check that ticket creation remains safe across repeated deliveries and worker retries. |
123
124Do not silently discard a verified notification when its case lookup fails. Keep it available for retry or investigation.
