--- title: Webhooks da organização url: https://platform.claude.com/docs/pt-BR/manage-claude/organization-webhooks description: Registre endpoints de webhook para eventos sobre ações de aplicação nos perfis de usuário da sua organização. featureMetadata: status: beta betaHeader: webhooks-2026-10-07 supportedPlatforms: Claude API: beta --- Um "organization webhook endpoint" (endpoint de webhook da organização) recebe um evento quando a Anthropic restringe ou bane um dos [perfis de usuário](https://platform.claude.com/docs/pt-BR/manage-claude/user-profiles) da sua organização, e quando a restrição ou o banimento termina. Você o gerencia com a Admin API em `/v1/organizations/webhooks`. A entrega de eventos não está ativa: a Anthropic não envia os dois eventos, então um endpoint que você registrar não recebe nada. Você pode registrar endpoints e criar seu handler a partir do formato de evento descrito nesta página. Qualquer membro da sua organização pode listar e visualizar endpoints de webhook da organização com a API, mas apenas membros com a função de admin, owner ou primary owner podem criá-los, alterá-los ou excluí-los, ou substituir seu segredo de assinatura. ## Antes de começar Você precisa do seguinte: * Uma organização na Claude API que tenha os webhooks da organização ativados e não tenha a [prontidão para HIPAA](https://platform.claude.com/docs/pt-BR/manage-claude/api-and-data-retention#hipaa-readiness) habilitada. Para solicitar acesso, entre em contato com sua equipe de conta da Anthropic. * Uma destas credenciais: * Uma [chave de Admin API](https://platform.claude.com/docs/pt-BR/manage-claude/admin-api-keys). * Um [token bearer OAuth](https://platform.claude.com/docs/pt-BR/manage-claude/admin-api#oauth-bearer-token) com o escopo `org:admin`. * Uma [chave pessoal ou de conta de serviço](https://platform.claude.com/docs/pt-BR/manage-claude/authentication#key-types) que não esteja restrita a um workspace. ## Tipos de evento Os endpoints de webhook da organização aceitam dois tipos de evento. Ambos tratam de "enforcement actions" (ações de aplicação) em perfis de usuário. Uma ação de aplicação é uma restrição ou um banimento que a Anthropic aplica ao cliente final que um perfil representa. | Evento | Gatilho | | ------------------------------------------ | ---------------------------------------------------------------------------------------------- | | `user_profile.enforcement_action_opened` | A Anthropic abre uma ação de aplicação em um perfil de usuário. | | `user_profile.enforcement_action_resolved` | Uma ação de aplicação termina. A Anthropic a resolve, ou o horário em `expires_at` é atingido. | Excluir um perfil encerra suas ações em aberto sem um evento `user_profile.enforcement_action_resolved`. ### Antes do seu primeiro evento Seus perfis não terão os campos `enforcement_status` e `enforcement_actions` até que as ações de aplicação estejam ativas para sua organização. Até lá, e em qualquer solicitação cujo cabeçalho `anthropic-beta` tenha `user-profiles-2026-09-04` ou um valor anterior, as respostas omitem esses campos e o filtro de lista `enforcement_status[]` retorna um `400`. Para obter os campos, remova esse valor das suas solicitações. Se uma ação de aplicação foi aberta antes de a Anthropic ativar as ações de aplicação e a entrega de eventos para sua organização, ou antes de você registrar seu endpoint, você não recebe um evento `user_profile.enforcement_action_opened` para ela. A ação ainda aparece no perfil. Para encontrar essas ações, [liste seus perfis](https://platform.claude.com/docs/pt-BR/api/user_profiles/list) com `enforcement_status[]=restricted` e `enforcement_status[]=banned`. Uma resposta pode retornar menos perfis do que `limit`, ou nenhum, antes de a lista terminar, então continue solicitando páginas até que `next_page` seja `null`. ### O que um evento contém Os eventos carregam IDs, não a ação nem o perfil. `data.id` é o ID do perfil, e `data.enforcement_action_id` é o ID da ação, que começa com `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" } } ``` Para ver o que mudou, [recupere o perfil](https://platform.claude.com/docs/pt-BR/api/user_profiles/retrieve) com `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`. A lista `enforcement_actions` do perfil mostra suas ações em aberto. Cada ação tem um `type` (`restriction` ou `ban`), um `id`, um `reason`, um horário `opened_at` e um horário `expires_at` ou `null`. `enforcement_status` as resume: `banned` enquanto um banimento estiver em aberto, `restricted` enquanto qualquer outra ação estiver em aberto, e `unrestricted` quando não houver nenhuma. Trate qualquer outro valor como `restricted`. A Anthropic envia um evento somente depois que o perfil mostra a mudança, então o perfil que você recupera mostra essa mudança ou uma posterior. Os eventos podem chegar atrasados ou fora de ordem, então use o estado atual do perfil, não a ordem em que os eventos chegam. Após `user_profile.enforcement_action_resolved`, a ação resolvida não está mais na lista. Um `404` significa que o perfil foi excluído. ## Campos do endpoint Um endpoint de webhook da organização tem estes campos: | Campo | Tipo | Descrição | | ----------------- | ---------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `id` | string | O ID do endpoint, que começa com `wep_`. Definido pela Anthropic. | | `url` | string | Para onde a Anthropic envia os eventos. Deve ser HTTPS na porta 443, com um nome de domínio público, não um endereço IP. Dois endpoints de webhook da organização habilitados na sua organização não podem compartilhar uma URL. | | `enabled_events` | array de strings | Os [tipos de evento](https://platform.claude.com/docs/pt-BR/manage-claude/organization-webhooks#event-types) que este endpoint recebe. Uma solicitação de criação deve listar pelo menos um. | | `name` | string | Um rótulo opcional para seu próprio uso. | | `description` | string | Uma descrição opcional para seu próprio uso. | | `state` | string | `enabled` ou `disabled`. | | `disabled_reason` | string | Por que a Anthropic desabilitou o endpoint. Vazio caso contrário. | | `created_at` | string | Quando o endpoint foi criado. Definido pela Anthropic. | | `updated_at` | string | Quando o endpoint foi alterado pela última vez. Definido pela Anthropic. | | `signing_secret` | string | Um segredo com prefixo `whsec_`, criado junto com o endpoint. Apenas as respostas que criam o endpoint ou substituem o segredo o incluem, então armazene-o com segurança. | ```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" } ``` Uma organização pode ter até 32 endpoints de webhook da organização. Endpoints de webhook desabilitados ainda contam para esse total. ## Entregas As entregas seguem a especificação [Standard Webhooks](https://www.standardwebhooks.com/). Cada uma carrega os cabeçalhos `webhook-id`, `webhook-timestamp` e `webhook-signature`. Antes de confiar em um evento, verifique sua assinatura com o segredo de assinatura do endpoint, usando qualquer biblioteca Standard Webhooks. Retorne qualquer status `2xx` em até 5 segundos e faça o trabalho demorado depois. Qualquer outra resposta, ou nenhuma resposta, conta como uma tentativa com falha. * **Duplicatas:** Um endpoint pode receber o mesmo evento mais de uma vez, com o mesmo `id` de evento (o mesmo valor do cabeçalho `webhook-id`). Faça a deduplicação com base nele. * **Novas tentativas:** Se uma entrega falhar, a Anthropic tenta novamente algumas vezes nos minutos seguintes. Se todas as tentativas falharem, a Anthropic descarta o evento. Para se atualizar, liste seus perfis por status de aplicação, como em [Antes do seu primeiro evento](https://platform.claude.com/docs/pt-BR/manage-claude/organization-webhooks#before-your-first-event). * **Desabilitação automática:** A Anthropic desabilita um endpoint quando: * Ele retorna um redirecionamento (`3xx`). * Sua URL resolve para um endereço IP não público. * Suas entregas continuam falhando. A Anthropic ignora eventos para um endpoint desabilitado e não os envia depois. ## Gerenciar endpoints Com a Admin API, você pode fazer estas solicitações: | Tarefa | Solicitação | | ---------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | Listar os endpoints da sua organização | [`GET /v1/organizations/webhooks`](https://platform.claude.com/docs/pt-BR/api/beta/organization/webhooks/list) | | Criar um endpoint | [`POST /v1/organizations/webhooks`](https://platform.claude.com/docs/pt-BR/api/beta/organization/webhooks/create) | | Obter um endpoint | [`GET /v1/organizations/webhooks/{webhook_endpoint_id}`](https://platform.claude.com/docs/pt-BR/api/beta/organization/webhooks/retrieve) | | Atualizar `url`, `name`, `description`, `enabled_events` ou `state` de um endpoint | [`POST /v1/organizations/webhooks/{webhook_endpoint_id}`](https://platform.claude.com/docs/pt-BR/api/beta/organization/webhooks/update) | | Excluir um endpoint | [`DELETE /v1/organizations/webhooks/{webhook_endpoint_id}`](https://platform.claude.com/docs/pt-BR/api/beta/organization/webhooks/delete) | | Substituir o segredo de assinatura | [`POST /v1/organizations/webhooks/{webhook_endpoint_id}/regenerate_signing_secret`](https://platform.claude.com/docs/pt-BR/api/beta/organization/webhooks/regenerate_signing_secret) | Em uma atualização, `enabled_events` substitui toda a lista de tipos de evento do endpoint. Uma lista vazia não limpa a lista: o endpoint mantém os tipos de evento que tinha. Para interromper as entregas, envie `"state": "disabled"` ou exclua o endpoint. Para reativar um endpoint, inclusive depois que a Anthropic o desabilitou, envie `"state": "enabled"` em uma solicitação de atualização. Quando você substitui o segredo de assinatura, o segredo antigo para de funcionar imediatamente. As entregas a partir de então, incluindo novas tentativas de eventos anteriores, são assinadas com o novo segredo, então atualize seu receptor imediatamente. Envie o cabeçalho `anthropic-beta: webhooks-2026-10-07` em todas as solicitações. O SDK e a CLI o enviam para você. Este exemplo lista os endpoints da sua organização, usando uma chave de Admin API de `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 ``` Sem endpoints, a API retorna uma lista vazia: ```json { "data": [], "has_more": false } ``` Uma listagem retorna até 20 endpoints por padrão. Defina `limit` para obter até 100. Se `has_more` for `true`, passe o `last_id` da resposta como `after_id` para obter a próxima página. Este exemplo cria um endpoint que recebe ambos os tipos de 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 ``` A resposta é o novo endpoint, conforme mostrado em [Campos do endpoint](https://platform.claude.com/docs/pt-BR/manage-claude/organization-webhooks#endpoint-fields), mais seu `signing_secret`. ## Erros Uma solicitação retorna um `400` se: * Sua `url` não atende às regras em [Campos do endpoint](https://platform.claude.com/docs/pt-BR/manage-claude/organization-webhooks#endpoint-fields), ou uma solicitação de criação não lista nenhum tipo de evento. A mensagem de erro informa o que está errado. * Sua organização não tem um workspace padrão. * Os webhooks da organização não estão disponíveis para sua organização porque o workspace padrão dela usa uma [chave de criptografia gerenciada pelo cliente](https://platform.claude.com/docs/pt-BR/manage-claude/cmek). A mensagem de erro informa isso. * Ela daria à sua organização mais de 32 endpoints de webhook da organização. * Ela coloca em `enabled_events` um tipo de evento diferente dos dois em [Tipos de evento](https://platform.claude.com/docs/pt-BR/manage-claude/organization-webhooks#event-types). A mensagem de erro lista os tipos aceitos. Uma solicitação retorna um `403` se a função da sua conta não incluir a permissão de que a solicitação precisa. O erro informa o nome dessa permissão. Uma solicitação retorna um `404` se: * Ela não envia o cabeçalho `anthropic-beta: webhooks-2026-10-07`. * A Anthropic não ativou os webhooks da organização para sua organização. * Sua organização tem a prontidão para HIPAA habilitada. * Ela usa um tipo de credencial que essas solicitações não aceitam. * Seu `webhook_endpoint_id` não corresponde a um endpoint na sua organização. Uma solicitação retorna um `409` se: * Ela faria dois endpoints de webhook da organização habilitados compartilharem uma URL. * Outra solicitação alterou os endpoints da sua organização ao mesmo tempo. Tente a solicitação novamente.