Claude Admin API Webhooks: Register Org Webhooks for User Profiles

On October 20, 2026, Anthropic added organization webhooks to the Claude Admin API. You use the /v1/organizations/webhooks endpoints to register webhook URLs for two specific event types: when Anthropic restricts or bans one of your organization's user profiles, and when that restriction or ban ends.

This feature is in beta. You must send the webhooks-2026-10-07 beta header on every request, and you need to contact your Anthropic account team to request access before you can register any endpoints. The release notes on the official documentation list these requirements as of October 20, 2026.

Requesting access for your organization#

You cannot enable organization webhooks simply by sending the beta header. The official documentation states that you must contact your Anthropic account team to request access. Once your account team enables the feature for your organization, you can use an Admin API key from the ANTHROPIC_API_KEY environment variable, or an org:admin OAuth token from ANTHROPIC_AUTH_TOKEN, to authenticate your requests. The Admin API is available across the ant CLI and the Python, TypeScript, C#, Go, Java, PHP, and Ruby SDKs under client.beta.organization.

How user profiles and webhooks interact#

On October 20, 2026, Anthropic launched user profiles so you can tell Anthropic which of your end customers each API request is for. If you operate a platform or gateway, or resell API access, a safety enforcement action can then apply to one end customer instead of your whole organization. The SDK and the ant CLI support the new /v1/user_profiles endpoints.

Organization webhooks complement user profiles. When a user profile faces a safety enforcement action, Anthropic restricts or bans that specific profile. Without webhooks, you would need to poll the /v1/user_profiles endpoints to detect changes. With webhooks, Anthropic pushes an event to your registered endpoint the moment the restriction happens, and another when it ends. This push model reduces latency and API traffic.

If you operate a gateway and need to track which customer is which, you can read our guide on Claude API User Profiles: Identify Each Customer.

Using the Admin API in the official SDKs#

On August 26, 2026, Anthropic made the Admin API available in the ant CLI and the Python, TypeScript, C#, Go, Java, PHP, and Ruby SDKs. These SDKs cover organization info, members, invites, workspaces and workspace members, API keys, rate limits, service accounts, workload identity federation issuers and rules, and customer-managed encryption keys. The webhooks endpoints were added later in October. You access these features under client.beta.organization.

When you write code to register a webhook, you read the Admin API key from ANTHROPIC_API_KEY or an org:admin OAuth token from ANTHROPIC_AUTH_TOKEN. The SDKs handle the authentication flow, but you still need to pass the webhooks-2026-10-07 beta header to opt in to the new endpoints.

The broader Admin API ecosystem#

The Admin API helps you manage your Claude Enterprise organization programmatically. On August 18, 2025, Anthropic added the Usage & Cost API and an endpoint for retrieving organization information. By August 26, 2026, the Admin API became available in the ant CLI and multiple SDKs under client.beta.organization.

You can use the Admin API to manage members, invites, groups, and custom roles. On August 19, 2026, the user-management endpoints for Claude Enterprise organizations moved out of beta. The ce-user-management-2026-07-13 beta header is no longer required on group and custom-role requests. You can also manage workspaces, workspace members, API keys, rate limits, service accounts, workload identity federation issuers and rules, and customer-managed encryption keys.

The organization webhooks fit into this ecosystem by giving you real-time updates on safety enforcement actions. If you need to audit how your team uses Claude, see our guide on How to Export Claude Instructions for Enterprise Audits.

Comparing Claude Managed Agents webhooks and Admin API webhooks#

Anthropic also offers webhooks for Claude Managed Agents. On May 6, 2026, Anthropic announced webhooks for Claude Managed Agents covering session and vault lifecycle events. By June 30, 2026, these webhooks expanded to cover agent, deployment, and deployment run lifecycle events. On July 22, 2026, they added environment and memory store lifecycle events.

The organization webhooks in the Admin API are different. They do not track agent sessions or deployments. Instead, they track safety enforcement actions on your user profiles. You use /v1/organizations/webhooks for admin-level events, while you use the Managed Agents endpoints for agent lifecycle events. Do not confuse the two when integrating your platform.

Constructing the webhook registration request#

The /v1/organizations/webhooks endpoint expects a POST request. The official documentation does not list the exact base URL, request body fields, or response shape for this endpoint yet, but you must include your webhook endpoint URL and subscribe to the two event types. You must also include the anthropic-version header on every request to the Claude Enterprise endpoints of the Admin API.

import json

def build_webhook_request(url):
    return {
        "method": "POST",
        "path": "/v1/organizations/webhooks",
        "headers": {
            "anthropic-version": "2023-06-01",
            "anthropic-beta": "webhooks-2026-10-07",
            "x-api-key": "$ANTHROPIC_API_KEY",
            "content-type": "application/json"
        },
        "body": {
            "url": url
        }
    }

request = build_webhook_request("https://example.com/webhooks/claude-admin")
print(json.dumps(request, indent=2))

This example shows the minimum components you need to construct the request. You send the anthropic-version header, the webhooks-2026-10-07 beta header, and your API key.

Handling restriction and reinstatement events#

The two event types you register for cover the lifecycle of a safety enforcement action on a user profile. When you resell API access or operate a gateway, a safety action can apply to a single end customer instead of your whole organization. The first event fires when Anthropic restricts or bans one of your organization's user profiles. The second event fires when the restriction or ban ends, allowing you to automatically reinstate the affected customer.

When your webhook endpoint receives an event, you should parse the payload to determine which user profile was affected and update your internal state accordingly. If you ignore the reinstatement event, your platform might keep a user blocked even after Anthropic restores their access.

Gotchas when working with the Claude Admin API#

1. Access is gated: The organization webhooks feature is in beta, and access is not automatic. You must contact your Anthropic account team to request access. If you try to call /v1/organizations/webhooks without access, the request will fail.
2. The beta header is mandatory: Send anthropic-beta: webhooks-2026-10-07 on every request to the webhooks endpoints. Without this header, the API will not recognize the request as part of the beta.
3. Admin API coverage varies by surface: The ant CLI and the Python, TypeScript, C#, Go, Java, PHP, and Ruby SDKs cover most Admin API endpoints under client.beta.organization. However, usage and cost reports, and the Claude Enterprise user-management and analytics endpoints, remain curl-only.
4. Inference hooks vs organization webhooks: Do not confuse the new organization webhooks with the recently graduated inference hooks. Inference hooks are out of beta for Claude Enterprise organizations as of October 20, 2026, but they serve a different purpose from the admin webhooks that track user profile restrictions.
5. API version header: Send anthropic-version on every request to the Claude Enterprise endpoints of the Admin API. The official documentation requires this header on all Admin API requests.

Preparing your gateway for safety enforcement actions#

If you operate a platform or gateway, or resell API access, user profiles let you tell Anthropic which of your end customers each API request is for. When a safety enforcement action applies to one end customer, the organization webhooks notify you immediately.

Your gateway should handle the restriction event by pausing the affected user's access. When you receive the reinstatement event, your gateway should restore their access. This automated flow prevents you from polling the /v1/user_profiles endpoints constantly. It also ensures your end customers experience minimal downtime if a safety action is lifted.

If your gateway needs to handle structured data, you might also find our guide on Claude Structured Outputs JSON Schema: Python Examples useful.

Managing API keys and OAuth tokens#

The CLI and SDKs read an Admin API key from ANTHROPIC_API_KEY or an org:admin OAuth token from ANTHROPIC_AUTH_TOKEN. When you register a webhook, you must use an Admin API key with the necessary permissions. If you use an OAuth token, ensure it has the org:admin scope.

The official documentation does not list a specific scope for the webhooks endpoints yet. However, on July 14, 2026, Anthropic noted that an Admin API key with the read:org_audit scope can call every user-management GET endpoint. You might need a similar scope for the webhooks endpoints, but the official docs do not confirm this. Contact your Anthropic account team if you encounter permission errors.

Checking the status of your webhooks#

Once you register a webhook, you can likely list your registered endpoints by sending a GET request to /v1/organizations/webhooks. The official documentation does not detail the list or delete endpoints yet, but standard REST API conventions suggest these methods exist. Use the same webhooks-2026-10-07 beta header and anthropic-version header on all requests to these endpoints.

If you need to update your webhook URL, you might need to delete the old webhook and register a new one. The official documentation does not specify an update method yet. Test your changes in a non-production environment before deploying them to your live gateway.

Verifying your webhook endpoint#

The official documentation does not list the specific signature headers or verification logic for the new organization webhooks yet. You should ensure your endpoint accepts POST requests and can handle the two event types: restriction and reinstatement. When the restriction or ban ends, your endpoint receives the reinstatement event, allowing your platform to restore the user's access. To secure your endpoint, use a secret token in your webhook URL and validate it in your handler, or restrict incoming requests to known Anthropic IP ranges if your infrastructure supports it.

Quick checklist for Claude Admin API webhooks#

• Request access from your Anthropic account team.
• Use an Admin API key from ANTHROPIC_API_KEY or an org:admin OAuth token from ANTHROPIC_AUTH_TOKEN.
• Send the anthropic-version header.
• Send the anthropic-beta: webhooks-2026-10-07 header.
• POST to /v1/organizations/webhooks with your endpoint URL.
• Handle both the restriction and reinstatement events to automate user profile states.
• Do not confuse these organization webhooks with inference hooks or other Claude Managed Agents webhooks.

Quick answers