organization-webhooks changedmanage-claude/organization-webhooks
Nearest release: v2.1.312, published under an hour before this site recorded the change. Shown because the two are within 24 hours of each other. Nothing here says the release caused the edit.
Recorded here
Lines+24added
Lines−24removed
From line
9
where the diff opens
First seen
21 Oct 2026
this site's first read of the page
Recorded edits6to this page, all time
The whole hunk
from line 9, old and new numbered
/
from line 9
99 Claude API: beta
1010---
1111
12An organization webhook endpoint receives an event when Anthropic restricts or bans one of your organization's [user profiles](https://platform.claude.com/docs/en/manage-claude/user-profiles), and when the restriction or ban ends. You manage it with the Admin API under `/v1/organizations/webhooks`.
12An organization webhook endpoint receives an event when Anthropic restricts or bans one of your organization’s [user profiles](https://platform.claude.com/docs/en/manage-claude/user-profiles), and when the restriction or ban ends. You manage it with the Admin API under `/v1/organizations/webhooks`.
1313
1414<Note>
15 Event delivery isn't live: Anthropic doesn't send the two events, so an endpoint you register receives nothing. You can register endpoints and build your handler from the event format on this page.
15 Event delivery isn’t live: Anthropic doesn’t send the two events, so an endpoint you register receives nothing. You can register endpoints and build your handler from the event format on this page.
1616</Note>
1717
1818Any member of your organization can list and view organization webhook endpoints with the API, but only members with the admin, owner, or primary owner role can create, change, or delete them, or replace their signing secret.
from line 21
2121
2222You need the following:
2323
24* An organization on the Claude API that has organization webhooks turned on and doesn't have [HIPAA readiness](https://platform.claude.com/docs/en/manage-claude/api-and-data-retention#hipaa-readiness) enabled. To request access, contact your Anthropic account team.
24* An organization on the Claude API that has organization webhooks turned on and doesn’t have [HIPAA readiness](https://platform.claude.com/docs/en/manage-claude/api-and-data-retention#hipaa-readiness) enabled. To request access, contact your Anthropic account team.
2525
2626* One of these credentials:
2727
2828 * An [Admin API key](https://platform.claude.com/docs/en/manage-claude/admin-api-keys).
2929 * An [OAuth bearer token](https://platform.claude.com/docs/en/manage-claude/admin-api#oauth-bearer-token) with the `org:admin` scope.
30 * A [personal or service account key](https://platform.claude.com/docs/en/manage-claude/authentication#key-types) that isn't scoped to a workspace.
30 * A [personal or service account key](https://platform.claude.com/docs/en/manage-claude/authentication#key-types) that isn’t scoped to a workspace.
3131
3232## Event types
3333
from line 44
4444
4545In any request whose `anthropic-beta` header has `user-profiles-2026-09-04` or an earlier value, responses leave out the `enforcement_status` and `enforcement_actions` fields and the `enforcement_status[]` list filter returns a `400`. To get the fields, remove that value from your requests.
4646
47If an enforcement action opened before Anthropic turned on event delivery for your organization, or before you registered your endpoint, you don't get a `user_profile.enforcement_action_opened` event for it. The action still appears on the profile. To find these actions, [list your profiles](https://platform.claude.com/docs/en/api/user_profiles/list) with `enforcement_status[]=restricted` and `enforcement_status[]=banned`. A response might return fewer profiles than `limit`, or none, before the list ends, so keep requesting pages until `next_page` is `null`.
47If an enforcement action opened before Anthropic turned on event delivery for your organization, or before you registered your endpoint, you don’t get a `user_profile.enforcement_action_opened` event for it. The action still appears on the profile. To find these actions, [list your profiles](https://platform.claude.com/docs/en/api/user_profiles/list) with `enforcement_status[]=restricted` and `enforcement_status[]=banned`. A response might return fewer profiles than `limit`, or none, before the list ends, so keep requesting pages until `next_page` is `null`.
4848
4949### What an event contains
5050
51Events carry IDs, not the action or the profile. `data.id` is the profile's ID, and `data.enforcement_action_id` is the action's ID, which starts with `enac_`:
51Events carry IDs, not the action or the profile. `data.id` is the profile’s ID, and `data.enforcement_action_id` is the action’s ID, which starts with `enac_`:
5252
5353```json
5454{
from line 66
6666
6767To see what changed, [retrieve the profile](https://platform.claude.com/docs/en/api/user_profiles/retrieve) with `GET /v1/user_profiles/{id}` (python, ruby: `client.user_profiles.retrieve()`; typescript: `client.userProfiles.retrieve()`; go: `client.UserProfiles.Get()`; java: `client.userProfiles().retrieve()`; csharp: `client.UserProfiles.Retrieve()`; php: `$client->userProfiles->retrieve()`; cli: `ant user-profiles retrieve`), using `data.id`. Its `enforcement_actions` list shows its open actions. Each action has a `type` (`restriction` or `ban`), an `id`, a `reason`, an `opened_at` time, and an `expires_at` time or `null`. `enforcement_status` summarizes them: `banned` while a ban is open, `restricted` while any other action is open, and `unrestricted` when none is. Treat any other value as `restricted`.
6868
69Anthropic sends an event only after the profile shows the change, so the profile you retrieve shows that change or a later one. Events might arrive late or out of order, so use the profile's current state, not the order events arrive in. After `user_profile.enforcement_action_resolved`, the resolved action is no longer in the list. A `404` means the profile was deleted.
69Anthropic sends an event only after the profile shows the change, so the profile you retrieve shows that change or a later one. Events might arrive late or out of order, so use the profile’s current state, not the order events arrive in. After `user_profile.enforcement_action_resolved`, the resolved action is no longer in the list. A `404` means the profile was deleted.
7070
7171## Endpoint fields
7272
from line 74
7474
7575| Field | Type | Description |
7676| ----------------- | ---------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
77| `id` | string | The endpoint's ID, which starts with `wep_`. Set by Anthropic. |
78| `url` | string | Where Anthropic sends events. Must be HTTPS on port 443, with a public domain name, not an IP address. Two enabled organization webhook endpoints in your organization can't share a URL. |
77| `id` | string | The endpoint’s ID, which starts with `wep_`. Set by Anthropic. |
78| `url` | string | Where Anthropic sends events. Must be HTTPS on port 443, with a public domain name, not an IP address. Two enabled organization webhook endpoints in your organization can’t share a URL. |
7979| `enabled_events` | array of strings | The [event types](https://platform.claude.com/docs/en/manage-claude/organization-webhooks#event-types) this endpoint receives. A create request must list at least one. |
8080| `name` | string | An optional label for your own use. |
8181| `description` | string | An optional description for your own use. |
from line 106
106106
107107## Deliveries
108108
109Deliveries follow the [Standard Webhooks](https://www.standardwebhooks.com/) specification. Each one carries the `webhook-id`, `webhook-timestamp`, and `webhook-signature` headers. Before you trust an event, verify its signature with the endpoint's signing secret, using any Standard Webhooks library.
109Deliveries follow the [Standard Webhooks](https://www.standardwebhooks.com/) specification. Each one carries the `webhook-id`, `webhook-timestamp`, and `webhook-signature` headers. Before you trust an event, verify its signature with the endpoint’s signing secret, using any Standard Webhooks library.
110110
111111Return any `2xx` status within 5 seconds, and do slow work afterward. Any other response, or no response, counts as a failed attempt.
112112
from line 120
120120 * Its URL resolves to a non-public IP address.
121121 * Its deliveries keep failing.
122122
123 Anthropic skips events for a disabled endpoint and doesn't send them later.
123 Anthropic skips events for a disabled endpoint and doesn’t send them later.
124124
125125## Manage endpoints
126126
from line 128
128128
129129| Task | Request |
130130| ------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
131| List your organization's endpoints | [`GET /v1/organizations/webhooks`](https://platform.claude.com/docs/en/api/beta/organization/webhooks/list) |
131| List your organization’s endpoints | [`GET /v1/organizations/webhooks`](https://platform.claude.com/docs/en/api/beta/organization/webhooks/list) |
132132| Create an endpoint | [`POST /v1/organizations/webhooks`](https://platform.claude.com/docs/en/api/beta/organization/webhooks/create) |
133133| Get one endpoint | [`GET /v1/organizations/webhooks/{webhook_endpoint_id}`](https://platform.claude.com/docs/en/api/beta/organization/webhooks/retrieve) |
134| Update an endpoint's `url`, `name`, `description`, `enabled_events`, or `state` | [`POST /v1/organizations/webhooks/{webhook_endpoint_id}`](https://platform.claude.com/docs/en/api/beta/organization/webhooks/update) |
134| Update an endpoint’s `url`, `name`, `description`, `enabled_events`, or `state` | [`POST /v1/organizations/webhooks/{webhook_endpoint_id}`](https://platform.claude.com/docs/en/api/beta/organization/webhooks/update) |
135135| Delete an endpoint | [`DELETE /v1/organizations/webhooks/{webhook_endpoint_id}`](https://platform.claude.com/docs/en/api/beta/organization/webhooks/delete) |
136136| Replace the signing secret | [`POST /v1/organizations/webhooks/{webhook_endpoint_id}/regenerate_signing_secret`](https://platform.claude.com/docs/en/api/beta/organization/webhooks/regenerate_signing_secret) |
137137
138In an update, `enabled_events` replaces the endpoint's whole list of event types. An empty list doesn't clear the list: the endpoint keeps the event types it had. To stop deliveries, send `"state": "disabled"` or delete the endpoint.
138In an update, `enabled_events` replaces the endpoint’s whole list of event types. An empty list doesn’t clear the list: the endpoint keeps the event types it had. To stop deliveries, send `"state": "disabled"` or delete the endpoint.
139139
140140To turn an endpoint back on, including after Anthropic disabled it, send `"state": "enabled"` in an update request.
141141
142142When you replace the signing secret, the old secret stops working at once. Deliveries from then on, including retries of earlier events, are signed with the new secret, so update your receiver right away.
143143
144Send the `anthropic-beta: webhooks-2026-10-07` header with every request. The SDK and the CLI send it for you. This example lists your organization's endpoints, using an Admin API key from `ANTHROPIC_API_KEY`.
144Send the `anthropic-beta: webhooks-2026-10-07` header with every request. The SDK and the CLI send it for you. This example lists your organization’s endpoints, using an Admin API key from `ANTHROPIC_API_KEY`.
145145
146146<CodeGroup>
147147 ```bash cURL
from line 239
239239}
240240```
241241
242A list returns up to 20 endpoints by default. Set `limit` to get up to 100. If `has_more` is `true`, pass the response's `last_id` as `after_id` to get the next page.
242A list returns up to 20 endpoints by default. Set `limit` to get up to 100. If `has_more` is `true`, pass the response’s `last_id` as `after_id` to get the next page.
243243
244244This example creates an endpoint that receives both event types:
245245
from line 391
391391
392392A request returns a `400` if:
393393
394* Its `url` doesn't meet the rules in [Endpoint fields](https://platform.claude.com/docs/en/manage-claude/organization-webhooks#endpoint-fields), or a create request lists no event types. The error message says what's wrong.
394* Its `url` doesn’t meet the rules in [Endpoint fields](https://platform.claude.com/docs/en/manage-claude/organization-webhooks#endpoint-fields), or a create request lists no event types. The error message says what’s wrong.
395395* Your organization has no default workspace.
396* Organization webhooks aren't available for your organization because its default workspace uses a [customer-managed encryption key](https://platform.claude.com/docs/en/manage-claude/cmek). The error message says so.
396* Organization webhooks aren’t available for your organization because its default workspace uses a [customer-managed encryption key](https://platform.claude.com/docs/en/manage-claude/cmek). The error message says so.
397397* It would give your organization more than 32 organization webhook endpoints.
398398* It puts an event type other than the two in [Event types](https://platform.claude.com/docs/en/manage-claude/organization-webhooks#event-types) in `enabled_events`. The error message lists the accepted types.
399399
400A request returns a `403` if your account's role doesn't include the permission the request needs. The error names that permission.
400A request returns a `403` if your account’s role doesn’t include the permission the request needs. The error names that permission.
401401
402402A request returns a `404` if:
403403
404* It doesn't send the `anthropic-beta: webhooks-2026-10-07` header.
405* Anthropic hasn't turned on organization webhooks for your organization.
404* It doesn’t send the `anthropic-beta: webhooks-2026-10-07` header.
405* Anthropic hasn’t turned on organization webhooks for your organization.
406406* Your organization has HIPAA readiness enabled.
407* It uses a kind of credential these requests don't accept.
408* Its `webhook_endpoint_id` doesn't match an endpoint in your organization.
407* It uses a kind of credential these requests don’t accept.
408* Its `webhook_endpoint_id` doesn’t match an endpoint in your organization.
409409
410410A request returns a `409` if:
411411
412412* It would make two enabled organization webhook endpoints share a URL.
413* Another request changed your organization's endpoints at the same time. Retry the request.
413* Another request changed your organization’s endpoints at the same time. Retry the request.
414414
No line in this hunk matches that.