Anthropic launched end-customer profiles and beta organization webhooks on October 20, 2026, then added enforcement status fields on October 21. Platforms can attribute requests to individual customers and inspect whether Anthropic has restricted or banned them. For a gateway operator, the implementation question is how to keep that state current before restoring customer access.
The current webhook documentation says event delivery is not live: registered endpoints receive nothing. Poll the profile API for current enforcement state. The webhook section below prepares for future delivery; it is not an active notification path as of October 22.
Once delivery starts, a resolved notification could arrive while another restriction is active. Restoring access from that notification alone would use an old event as a current authorization decision.
The procedure below targets a gateway calling the direct Claude API. It combines documented API behavior with our recommended recovery policy. General Analysis has not exercised a live integration for this guide.
Bind the profile to the authenticated customer#
Choose the identity boundary before creating records. Anthropic's profile guide defines application profiles for individual users of a product and passthrough profiles for companies buying resold API access. Store the returned uprof_ ID with the customer and send it through anthropic-user-profile-id on their requests. Keep internal usage in a separate organization; workspaces do not provide that separation.
Resolve the ID from your authenticated customer record. Strip customer-supplied attribution headers at the gateway boundary and replace them with your stored mapping. A caller who can choose another customer's profile can corrupt the attribution your response process depends on.
Serialize onboarding for each customer. Profile creation is not idempotent, and a repeated reference_id does not deduplicate it. If creation times out, preserve the uncertain attempt for reconciliation instead of blindly creating another profile. Check the creation reference when choosing fields; a reference ID helps correlation but is not proof that two records are the same customer.
Log the authenticated customer, selected profile, provider organization, and request outcome together, without copying prompt content into an identity log. Alert on a missing mapping before forwarding customer traffic. Do not remove the profile header or switch organizations to work around a restriction.
See how your AI systems hold up under real attacks
General Analysis maps AI applications and agents, red teams prompts, retrieval, tools, MCP servers, browser actions, permissions, and business workflows, then turns findings into evidence your team can reproduce and retest.
Prepare for future webhook delivery#
Organization webhooks support endpoint registration in beta, with account-team enablement and the webhooks-2026-10-07 header. Anthropic currently sends neither event. Use polling for operational decisions while preparing a receiver from the documented event format. Check eligibility before building around them: HIPAA readiness is excluded, and a default workspace using customer-managed encryption prevents webhook management. Use a documented credential with an admin or owner role to register an HTTPS endpoint.
Prepare to subscribe to both user_profile.enforcement_action_opened and user_profile.enforcement_action_resolved. The documented events identify the profile and action; retrieve the profile for its current state when delivery becomes available. Earlier actions are not replayed to a newly registered endpoint. Delivery retries are limited, and events skipped while an endpoint is disabled are not sent later.
For the future receiver, use an intake service. Follow the Standard Webhooks specification to verify signatures over the original body and enforce timestamp tolerance. Validate the expected organization, then durably queue the event with an event-ID uniqueness constraint. Return a successful response within Anthropic's five-second deadline only after that durable handoff. Keep slow API lookups in the worker.
When delivery starts, monitor queue age and endpoint state. A receiver returning success while its worker is stuck still leaves customer decisions stale. Set a freshness limit that matches the workflow's risk and assign an owner for breaches of that limit.
Refresh state before changing access#
The retrieve endpoint returns the profile's current enforcement fields. Keep the provider observation separate from your own customer status. A provider resolution should never clear a suspension imposed by your fraud, billing, or incident-response process.
Use one serialized refresh path per profile for scheduled polling and any future webhook jobs. Otherwise, an older lookup can finish after a newer one and overwrite it. Save the observation time and the source of each refresh alongside the returned action IDs. Serialization orders your writes; it does not make the provider state immutable between requests.
The following is illustrative Python-style pseudocode for an application-owned access decision. The helpers represent your queue, persistence, and Claude API client; this is not a runnable SDK integration. hold means the gateway pauses customer traffic for review or retry, not that Anthropic returns a status named hold.
Code source: illustrative.
def refresh_customer(customer_id):
with customer_refresh_lock(customer_id):
customer = load_customer(customer_id)
try:
profile = retrieve_profile(customer.profile_id)
except ProfileNotFound:
save_provider_observation(customer_id, "missing")
return set_gateway_access(customer_id, "hold")
except ProviderUnavailable:
mark_observation_stale(customer_id)
return set_gateway_access(customer_id, "hold")
status = profile.get("enforcement_status")
actions = profile.get("enforcement_actions")
save_provider_observation(customer_id, status, actions)
provider_clear = status == "unrestricted" and actions == []
# Re-read local policy inside the same atomic access update.
update_access_atomically(
customer_id,
allow_only_if_provider_clear=provider_clear,
require_local_account_active=True,
)
This deliberately conservative policy holds missing, unfamiliar, or inconsistent state. It also pauses on a lookup outage, trading availability for a decision based on current evidence. Define and review any different outage policy explicitly; do not let an exception handler silently restore access.
Check the deployment before trusting those fields. The current profile documentation says Claude Platform on AWS always reports unrestricted with an empty action list and does not refuse inference because of an open action. That response cannot establish enforcement coverage there. Old user-profiles-2026-09-04 or earlier beta headers also omit the fields; remove them before evaluating this integration.
Reconcile between polling runs#
At startup and after an outage, reconcile the profiles linked to your active or held customers. Fetch every mapped profile through the same refresh path. This catches a restriction that ended between observations while retaining any independent local suspension. The same refresh path can recover missed notifications once delivery starts.
For a large population, the list endpoint supports filtering for restricted and banned profiles. Follow next_page until it is null: a filtered page can be empty while more pages remain. The API also defines a pending status. A sweep of only restricted and banned profiles therefore cannot establish that every other customer is unrestricted.
Use a filtered sweep to discover those listed states, then separately refresh customers already on hold and any observation that exceeds your freshness limit. Absence from a filtered result is not permission to clear a hold. If a page fails, record the sweep as incomplete and resume or restart it; do not treat the partial set as a complete account snapshot.
For polling, compare the enforcement fields themselves. Anthropic warns that their changes do not reliably advance updated_at. Store enough history to explain your own access decisions, with a retention policy appropriate to that evidence. Current profile state alone cannot reconstruct every restriction that existed during a collection outage.
Check recovery before accepting customer traffic#
Use synthetic profile responses for these acceptance cases. Exercise the future webhook cases with a local receiver harness; live event delivery is unavailable. These are proposed checks, not results measured by General Analysis. Do not generate abusive production requests to induce a real restriction.
| Case | Required gateway behavior |
|---|---|
| A resolved notification arrives, but the current profile has another open action | Retain the hold and record the current action IDs. |
| A duplicate event arrives | Preserve one intake record; retries must not produce conflicting access decisions. |
| A filtered list page is empty but has a cursor | Continue the sweep; do not report completion yet. |
| A locally suspended customer becomes unrestricted at the provider | Preserve the local suspension. |
| A profile lookup fails or returns unfamiliar state | Mark the decision unresolved; apply the documented outage policy. |
| A profile is deleted | Remove its usable mapping and retain a hold until the customer lifecycle is reconciled. |
Anthropic's webhook contract says deletion ends open actions without a resolved notification. Keep a missing profile unresolved until you know why it disappeared.
Save the expected outcome, observed gateway decision, and persisted record for each case. Then verify a harmless attributed request with a permitted test customer and confirm which identity reached the provider. Keep application authorization and AI guardrails in place: a provider's unrestricted status does not approve a particular tool action. Use the Managed Agents approval procedure where sensitive actions require a reviewer.
Assign the operator who handles stale observations, missing mappings, and restriction appeals before rollout. If you also need employee session evidence, collect it through the separate Claude Compliance API workflow; these customer-profile notifications are not a session audit feed.
