Organization webhooks

An organization webhook endpoint receives an event when Anthropic restricts or bans one of your organization's user profiles, and when the restriction or ban ends. You manage it with the Admin API under /v1/organizations/webhooks.

Any 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.

Before you begin

You need the following:

• An organization on the Claude API that has organization webhooks turned on and doesn't have HIPAA readiness enabled. To request access, contact your Anthropic account team.
• One of these credentials:
  • An Admin API key.
  • An OAuth bearer token with the org:admin scope.
  • A personal or service account key that isn't scoped to a workspace.

Event types

Organization webhook endpoints accept two event types. Both are about enforcement actions on user profiles. An enforcement action is a restriction or a ban that Anthropic places on the end customer a profile represents.

Deleting a profile ends its open actions without a user_profile.enforcement_action_resolved event.

Before your first event

Your profiles won't have the enforcement_status and enforcement_actions fields until enforcement actions are on for your organization. Until then, and in any request whose anthropic-beta header has user-profiles-2026-09-04 or an earlier value, responses leave the fields out and the enforcement_status[] list filter returns a 400. To get the fields, remove that value from your requests.

If an enforcement action opened before Anthropic turned on enforcement actions and 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 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.

What an event contains

Events 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_:

{
  "type": "event",
  "id": "whe_4f2a9c1e7b3d5a8f0e6c2b9d1a7f3e5c",
  "created_at": "2026-10-15T17:02:41Z",
  "data": {
    "type": "user_profile.enforcement_action_opened",
    "id": "uprof_011CZkZCu8hGbp5mYRQgUmz9",
    "enforcement_action_id": "enac_011CZkZEq4TnWb7xLfRgPm2v",
    "organization_id": "org_011CZkZBj9RsYd3wNcHvKq6t"
  }
}

To see what changed, retrieve the profile with client.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.

Anthropic 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.

Endpoint fields

An organization webhook endpoint has these fields:

{
  "id": "wep_011CZkZDf8HnUq2mTxRbVn4s",
  "url": "https://example.com/anthropic-webhooks",
  "name": "Enforcement actions",
  "description": "",
  "enabled_events": [
    "user_profile.enforcement_action_opened",
    "user_profile.enforcement_action_resolved"
  ],
  "state": "enabled",
  "disabled_reason": "",
  "created_at": "2026-10-20T19:00:00Z",
  "updated_at": "2026-10-20T19:00:00Z"
}

An organization can have up to 32 organization webhook endpoints. Disabled webhook endpoints still count toward this total.

Deliveries

Deliveries follow the Standard Webhooks 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.

Return any 2xx status within 5 seconds, and do slow work afterward. Any other response, or no response, counts as a failed attempt.

• Duplicates: An endpoint might receive the same event more than once, with the same event id (the same value as the webhook-id header). Deduplicate on it.

• Retries: If a delivery fails, Anthropic retries it a few times over the next few minutes. If every attempt fails, Anthropic drops the event. To catch up, list your profiles by enforcement status, as in Before your first event.

• Automatic disabling: Anthropic disables an endpoint when:

  • It returns a redirect (3xx).
  • Its URL resolves to a non-public IP address.
  • Its deliveries keep failing.

  Anthropic skips events for a disabled endpoint and doesn't send them later.

Manage endpoints

With the Admin API, you can make these requests:

In 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.

To turn an endpoint back on, including after Anthropic disabled it, send "state": "enabled" in an update request.

When 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.

Send 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.

client = anthropic.Anthropic()

endpoints = client.beta.organization.webhooks.list()

for endpoint in endpoints:
    print(f"{endpoint.id}: {endpoint.url} ({endpoint.state})")

With no endpoints, the API returns an empty list:

{
  "data": [],
  "has_more": false
}

A 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.

This example creates an endpoint that receives both event types:

client = anthropic.Anthropic()

endpoint = client.beta.organization.webhooks.create(
    url="https://example.com/anthropic-webhooks",
    name="Enforcement actions",
    enabled_events=[
        "user_profile.enforcement_action_opened",
        "user_profile.enforcement_action_resolved",
    ],
)

print(endpoint.id)

The response is the new endpoint, as shown in Endpoint fields, plus its signing_secret.

Errors

A request returns a 400 if:

• Its url doesn't meet the rules in Endpoint fields, or a create request lists no event types. The error message says what's wrong.
• Your organization has no default workspace.
• Organization webhooks aren't available for your organization because its default workspace uses a customer-managed encryption key. The error message says so.
• It would give your organization more than 32 organization webhook endpoints.
• It puts an event type other than the two in Event types in enabled_events. The error message lists the accepted types.

A request returns a 403 if your account's role doesn't include the permission the request needs. The error names that permission.

A request returns a 404 if:

• It doesn't send the anthropic-beta: webhooks-2026-10-07 header.
• Anthropic hasn't turned on organization webhooks for your organization.
• Your organization has HIPAA readiness enabled.
• It uses a kind of credential these requests don't accept.
• Its webhook_endpoint_id doesn't match an endpoint in your organization.

A request returns a 409 if:

• It would make two enabled organization webhook endpoints share a URL.
• Another request changed your organization's endpoints at the same time. Retry the request.

Compatibility