--- title: Webhook dell'organizzazione url: https://platform.claude.com/docs/it/manage-claude/organization-webhooks description: Registra endpoint webhook per ricevere eventi sulle azioni di applicazione che riguardano i profili utente della tua organizzazione. featureMetadata: status: beta betaHeader: webhooks-2026-10-07 supportedPlatforms: Claude API: beta --- Un endpoint webhook dell'organizzazione riceve un evento quando Anthropic limita o banna uno dei [profili utente](https://platform.claude.com/docs/it/manage-claude/user-profiles) della tua organizzazione, e quando la limitazione o il ban terminano. Lo gestisci con l'Admin API in `/v1/organizations/webhooks`. La consegna degli eventi non è attiva: Anthropic non invia i due eventi, quindi un endpoint che registri non riceve nulla. Puoi registrare gli endpoint e costruire il tuo gestore a partire dal formato degli eventi descritto in questa pagina. Qualsiasi membro della tua organizzazione può elencare e visualizzare gli endpoint webhook dell'organizzazione con l'API, ma solo i membri con il ruolo di admin, owner o primary owner possono crearli, modificarli o eliminarli, oppure sostituirne il "signing secret" (segreto di firma). ## Prima di iniziare Ti serve quanto segue: * Un'organizzazione sulla Claude API che abbia i webhook dell'organizzazione attivati e non abbia la [predisposizione HIPAA](https://platform.claude.com/docs/it/manage-claude/api-and-data-retention#hipaa-readiness) abilitata. Per richiedere l'accesso, contatta il tuo team account Anthropic. * Una di queste credenziali: * Una [chiave Admin API](https://platform.claude.com/docs/it/manage-claude/admin-api-keys). * Un [token bearer OAuth](https://platform.claude.com/docs/it/manage-claude/admin-api#oauth-bearer-token) con lo scope `org:admin`. * Una [chiave personale o di service account](https://platform.claude.com/docs/it/manage-claude/authentication#key-types) non limitata a un workspace. ## Tipi di evento Gli endpoint webhook dell'organizzazione accettano due tipi di evento. Entrambi riguardano le "enforcement actions" (azioni di applicazione) sui profili utente. Un'azione di applicazione è una limitazione o un ban che Anthropic applica al cliente finale rappresentato da un profilo. | Evento | Attivazione | | ------------------------------------------ | ---------------------------------------------------------------------------------------------------------- | | `user_profile.enforcement_action_opened` | Anthropic apre un'azione di applicazione su un profilo utente. | | `user_profile.enforcement_action_resolved` | Un'azione di applicazione termina. Anthropic la risolve, oppure viene superato il suo orario `expires_at`. | L'eliminazione di un profilo chiude le sue azioni aperte senza un evento `user_profile.enforcement_action_resolved`. ### Prima del tuo primo evento I tuoi profili non avranno i campi `enforcement_status` e `enforcement_actions` finché le azioni di applicazione non saranno attive per la tua organizzazione. Fino ad allora, e in qualsiasi richiesta il cui header `anthropic-beta` contenga `user-profiles-2026-09-04` o un valore precedente, le risposte omettono questi campi e il filtro di elenco `enforcement_status[]` restituisce un `400`. Per ottenere i campi, rimuovi quel valore dalle tue richieste. Se un'azione di applicazione è stata aperta prima che Anthropic attivasse le azioni di applicazione e la consegna degli eventi per la tua organizzazione, o prima che registrassi il tuo endpoint, non ricevi un evento `user_profile.enforcement_action_opened` per essa. L'azione compare comunque sul profilo. Per trovare queste azioni, [elenca i tuoi profili](https://platform.claude.com/docs/it/api/user_profiles/list) con `enforcement_status[]=restricted` e `enforcement_status[]=banned`. Una risposta potrebbe restituire meno profili di `limit`, o nessuno, prima della fine dell'elenco, quindi continua a richiedere pagine finché `next_page` non è `null`. ### Cosa contiene un evento Gli eventi contengono ID, non l'azione o il profilo. `data.id` è l'ID del profilo e `data.enforcement_action_id` è l'ID dell'azione, che inizia con `enac_`: ```json { "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" } } ``` Per vedere cosa è cambiato, [recupera il profilo](https://platform.claude.com/docs/it/api/user_profiles/retrieve) con `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`), usando `data.id`. Il suo elenco `enforcement_actions` mostra le azioni aperte. Ogni azione ha un `type` (`restriction` o `ban`), un `id`, un `reason`, un orario `opened_at` e un orario `expires_at` oppure `null`. `enforcement_status` le riassume: `banned` mentre è aperto un ban, `restricted` mentre è aperta qualsiasi altra azione e `unrestricted` quando non ce n'è nessuna. Tratta qualsiasi altro valore come `restricted`. Anthropic invia un evento solo dopo che il profilo mostra la modifica, quindi il profilo che recuperi mostra quella modifica o una successiva. Gli eventi potrebbero arrivare in ritardo o fuori ordine, quindi usa lo stato attuale del profilo, non l'ordine in cui arrivano gli eventi. Dopo `user_profile.enforcement_action_resolved`, l'azione risolta non è più nell'elenco. Un `404` significa che il profilo è stato eliminato. ## Campi dell'endpoint Un endpoint webhook dell'organizzazione ha questi campi: | Campo | Tipo | Descrizione | | ----------------- | ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `id` | string | L'ID dell'endpoint, che inizia con `wep_`. Impostato da Anthropic. | | `url` | string | Dove Anthropic invia gli eventi. Deve essere HTTPS sulla porta 443, con un nome di dominio pubblico, non un indirizzo IP. Due endpoint webhook dell'organizzazione abilitati nella tua organizzazione non possono condividere un URL. | | `enabled_events` | array of strings | I [tipi di evento](https://platform.claude.com/docs/it/manage-claude/organization-webhooks#event-types) che questo endpoint riceve. Una richiesta di creazione deve elencarne almeno uno. | | `name` | string | Un'etichetta facoltativa per uso personale. | | `description` | string | Una descrizione facoltativa per uso personale. | | `state` | string | `enabled` o `disabled`. | | `disabled_reason` | string | Il motivo per cui Anthropic ha disabilitato l'endpoint. Vuoto altrimenti. | | `created_at` | string | Quando è stato creato l'endpoint. Impostato da Anthropic. | | `updated_at` | string | Quando l'endpoint è stato modificato l'ultima volta. Impostato da Anthropic. | | `signing_secret` | string | Un segreto con prefisso `whsec_`, creato insieme all'endpoint. Solo le risposte che creano l'endpoint o sostituiscono il segreto lo includono, quindi conservalo in modo sicuro. | ```json { "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" } ``` Un'organizzazione può avere fino a 32 endpoint webhook dell'organizzazione. Anche gli endpoint webhook disabilitati contano ai fini di questo totale. ## Consegne Le consegne seguono la specifica [Standard Webhooks](https://www.standardwebhooks.com/). Ognuna contiene gli header `webhook-id`, `webhook-timestamp` e `webhook-signature`. Prima di considerare attendibile un evento, verificane la firma con il segreto di firma dell'endpoint, usando qualsiasi libreria Standard Webhooks. Restituisci qualsiasi stato `2xx` entro 5 secondi ed esegui le operazioni lente in seguito. Qualsiasi altra risposta, o l'assenza di risposta, conta come tentativo fallito. * **Duplicati:** un endpoint potrebbe ricevere lo stesso evento più di una volta, con lo stesso `id` dell'evento (lo stesso valore dell'header `webhook-id`). Usalo per eliminare i duplicati. * **Nuovi tentativi:** se una consegna fallisce, Anthropic la ritenta alcune volte nei minuti successivi. Se tutti i tentativi falliscono, Anthropic scarta l'evento. Per recuperare, elenca i tuoi profili per stato di applicazione, come in [Prima del tuo primo evento](https://platform.claude.com/docs/it/manage-claude/organization-webhooks#before-your-first-event). * **Disabilitazione automatica:** Anthropic disabilita un endpoint quando: * Restituisce un reindirizzamento (`3xx`). * Il suo URL si risolve in un indirizzo IP non pubblico. * Le sue consegne continuano a fallire. Anthropic salta gli eventi per un endpoint disabilitato e non li invia in seguito. ## Gestisci gli endpoint Con l'Admin API, puoi effettuare queste richieste: | Attività | Richiesta | | ---------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Elencare gli endpoint della tua organizzazione | [`GET /v1/organizations/webhooks`](https://platform.claude.com/docs/it/api/beta/organization/webhooks/list) | | Creare un endpoint | [`POST /v1/organizations/webhooks`](https://platform.claude.com/docs/it/api/beta/organization/webhooks/create) | | Ottenere un endpoint | [`GET /v1/organizations/webhooks/{webhook_endpoint_id}`](https://platform.claude.com/docs/it/api/beta/organization/webhooks/retrieve) | | Aggiornare `url`, `name`, `description`, `enabled_events` o `state` di un endpoint | [`POST /v1/organizations/webhooks/{webhook_endpoint_id}`](https://platform.claude.com/docs/it/api/beta/organization/webhooks/update) | | Eliminare un endpoint | [`DELETE /v1/organizations/webhooks/{webhook_endpoint_id}`](https://platform.claude.com/docs/it/api/beta/organization/webhooks/delete) | | Sostituire il segreto di firma | [`POST /v1/organizations/webhooks/{webhook_endpoint_id}/regenerate_signing_secret`](https://platform.claude.com/docs/it/api/beta/organization/webhooks/regenerate_signing_secret) | In un aggiornamento, `enabled_events` sostituisce l'intero elenco dei tipi di evento dell'endpoint. Un elenco vuoto non svuota l'elenco: l'endpoint mantiene i tipi di evento che aveva. Per interrompere le consegne, invia `"state": "disabled"` oppure elimina l'endpoint. Per riattivare un endpoint, anche dopo che Anthropic lo ha disabilitato, invia `"state": "enabled"` in una richiesta di aggiornamento. Quando sostituisci il segreto di firma, il vecchio segreto smette immediatamente di funzionare. Le consegne da quel momento in poi, compresi i nuovi tentativi di eventi precedenti, sono firmate con il nuovo segreto, quindi aggiorna subito il tuo ricevitore. Invia l'header `anthropic-beta: webhooks-2026-10-07` con ogni richiesta. L'SDK e la CLI lo inviano per te. Questo esempio elenca gli endpoint della tua organizzazione, usando una chiave Admin API da `ANTHROPIC_API_KEY`. ```bash cURL curl "https://api.anthropic.com/v1/organizations/webhooks" \ -H "x-api-key: $ANTHROPIC_API_KEY" \ -H "anthropic-version: 2023-06-01" \ -H "anthropic-beta: webhooks-2026-10-07" ``` ```bash CLI ant beta:organization:webhooks list ``` ```python Python client = anthropic.Anthropic() endpoints = client.beta.organization.webhooks.list() for endpoint in endpoints: print(f"{endpoint.id}: {endpoint.url} ({endpoint.state})") ``` ```typescript TypeScript const client = new Anthropic(); const endpoints = await client.beta.organization.webhooks.list(); for await (const endpoint of endpoints) { console.log(`${endpoint.id}: ${endpoint.url} (${endpoint.state})`); } ``` ```csharp C# AnthropicClient client = new(); var page = await client.Beta.Organization.Webhooks.List(); await foreach (var endpoint in page.Paginate()) { Console.WriteLine($"{endpoint.ID}: {endpoint.Url} ({endpoint.State.Raw()})"); } ``` ```go Go client := anthropic.NewClient() endpoints := client.Beta.Organization.Webhooks.ListAutoPaging(context.Background(), anthropic.BetaOrganizationWebhookListParams{}) for endpoints.Next() { endpoint := endpoints.Current() fmt.Printf("%s: %s (%s)\n", endpoint.ID, endpoint.URL, endpoint.State) } if err := endpoints.Err(); err != nil { log.Fatal(err) } ``` ```java Java AnthropicClient client = AnthropicOkHttpClient.fromEnv(); var endpoints = client.beta().organization().webhooks().list(); for (var endpoint : endpoints.autoPager()) { IO.println(endpoint.id() + ": " + endpoint.url() + " (" + endpoint.state().asString() + ")"); } ``` ```php PHP $client = new Client(); $endpoints = $client->beta->organization->webhooks->list(); foreach ($endpoints->pagingEachItem() as $endpoint) { echo "{$endpoint->id}: {$endpoint->url} ({$endpoint->state})\n"; } ``` ```ruby Ruby client = Anthropic::Client.new endpoints = client.beta.organization.webhooks.list endpoints.auto_paging_each do |endpoint| puts "#{endpoint.id}: #{endpoint.url} (#{endpoint.state})" end ``` Senza endpoint, l'API restituisce un elenco vuoto: ```json { "data": [], "has_more": false } ``` Un elenco restituisce fino a 20 endpoint per impostazione predefinita. Imposta `limit` per ottenerne fino a 100. Se `has_more` è `true`, passa il `last_id` della risposta come `after_id` per ottenere la pagina successiva. Questo esempio crea un endpoint che riceve entrambi i tipi di evento: ```bash cURL curl "https://api.anthropic.com/v1/organizations/webhooks" \ -H "x-api-key: $ANTHROPIC_API_KEY" \ -H "anthropic-version: 2023-06-01" \ -H "anthropic-beta: webhooks-2026-10-07" \ -H "content-type: application/json" \ -d '{ "url": "https://example.com/anthropic-webhooks", "name": "Enforcement actions", "enabled_events": [ "user_profile.enforcement_action_opened", "user_profile.enforcement_action_resolved" ] }' ``` ```bash CLI ant beta:organization:webhooks create \ --url https://example.com/anthropic-webhooks \ --name "Enforcement actions" \ --enabled-event user_profile.enforcement_action_opened \ --enabled-event user_profile.enforcement_action_resolved ``` ```python Python 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) ``` ```typescript TypeScript const client = new Anthropic(); const endpoint = await 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" ] }); console.log(endpoint.id); ``` ```csharp C# using Anthropic.Models.Beta.Organization.Webhooks; AnthropicClient client = new(); var endpoint = await client.Beta.Organization.Webhooks.Create(new WebhookCreateParams { UrlValue = "https://example.com/anthropic-webhooks", Name = "Enforcement actions", EnabledEvents = [ EnabledEvent.UserProfileEnforcementActionOpened, EnabledEvent.UserProfileEnforcementActionResolved, ], }); Console.WriteLine(endpoint.ID); ``` ```go Go client := anthropic.NewClient() endpoint, err := client.Beta.Organization.Webhooks.New(context.Background(), anthropic.BetaOrganizationWebhookNewParams{ URL: "https://example.com/anthropic-webhooks", Name: anthropic.String("Enforcement actions"), EnabledEvents: []string{ "user_profile.enforcement_action_opened", "user_profile.enforcement_action_resolved", }, }) if err != nil { log.Fatal(err) } fmt.Println(endpoint.ID) ``` ```java Java import com.anthropic.models.beta.organization.webhooks.WebhookCreateParams; void main() { AnthropicClient client = AnthropicOkHttpClient.fromEnv(); var params = WebhookCreateParams.builder() .url("https://example.com/anthropic-webhooks") .name("Enforcement actions") .addEnabledEvent(WebhookCreateParams.EnabledEvent.USER_PROFILE_ENFORCEMENT_ACTION_OPENED) .addEnabledEvent(WebhookCreateParams.EnabledEvent.USER_PROFILE_ENFORCEMENT_ACTION_RESOLVED) .build(); var endpoint = client.beta().organization().webhooks().create(params); IO.println(endpoint.id()); } ``` ```php PHP $client = new Client(); $endpoint = $client->beta->organization->webhooks->create( url: 'https://example.com/anthropic-webhooks', name: 'Enforcement actions', enabledEvents: [ 'user_profile.enforcement_action_opened', 'user_profile.enforcement_action_resolved', ], ); echo $endpoint->id, "\n"; ``` ```ruby Ruby client = Anthropic::Client.new 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" ] ) puts endpoint.id ``` La risposta è il nuovo endpoint, come mostrato in [Campi dell'endpoint](https://platform.claude.com/docs/it/manage-claude/organization-webhooks#endpoint-fields), più il suo `signing_secret`. ## Errori Una richiesta restituisce un `400` se: * Il suo `url` non rispetta le regole in [Campi dell'endpoint](https://platform.claude.com/docs/it/manage-claude/organization-webhooks#endpoint-fields), oppure una richiesta di creazione non elenca alcun tipo di evento. Il messaggio di errore indica il problema. * La tua organizzazione non ha un workspace predefinito. * I webhook dell'organizzazione non sono disponibili per la tua organizzazione perché il suo workspace predefinito usa una [chiave di crittografia gestita dal cliente](https://platform.claude.com/docs/it/manage-claude/cmek). Il messaggio di errore lo indica. * Porterebbe la tua organizzazione ad avere più di 32 endpoint webhook dell'organizzazione. * Inserisce in `enabled_events` un tipo di evento diverso dai due indicati in [Tipi di evento](https://platform.claude.com/docs/it/manage-claude/organization-webhooks#event-types). Il messaggio di errore elenca i tipi accettati. Una richiesta restituisce un `403` se il ruolo del tuo account non include l'autorizzazione necessaria per la richiesta. L'errore indica il nome di tale autorizzazione. Una richiesta restituisce un `404` se: * Non invia l'header `anthropic-beta: webhooks-2026-10-07`. * Anthropic non ha attivato i webhook dell'organizzazione per la tua organizzazione. * La tua organizzazione ha la predisposizione HIPAA abilitata. * Usa un tipo di credenziale che queste richieste non accettano. * Il suo `webhook_endpoint_id` non corrisponde a un endpoint della tua organizzazione. Una richiesta restituisce un `409` se: * Farebbe sì che due endpoint webhook dell'organizzazione abilitati condividano un URL. * Un'altra richiesta ha modificato contemporaneamente gli endpoint della tua organizzazione. Ritenta la richiesta.