Webhook dell'organizzazione

Un endpoint webhook dell'organizzazione riceve un evento quando Anthropic limita o banna uno dei profili utente della tua organizzazione, e quando la limitazione o il ban terminano. Lo gestisci con l'Admin API in /v1/organizations/webhooks.

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 abilitata. Per richiedere l'accesso, contatta il tuo team account Anthropic.
• Una di queste credenziali:
  • Una chiave Admin API.
  • Un token bearer OAuth con lo scope org:admin.
  • Una chiave personale o di service account 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.

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

{
  "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 con client.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:

{
  "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. 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.

• 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:

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.

client = anthropic.Anthropic()

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

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

Senza endpoint, l'API restituisce un elenco vuoto:

{
  "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:

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)

La risposta è il nuovo endpoint, come mostrato in Campi dell'endpoint, più il suo signing_secret.

Errori

Una richiesta restituisce un 400 se:

• Il suo url non rispetta le regole in Campi dell'endpoint, 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. 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. 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.

Compatibility