Webhooks da organização

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 da sua organização, e quando a restrição ou o banimento termina. Você o gerencia com a Admin API em /v1/organizations/webhooks.

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 habilitada. Para solicitar acesso, entre em contato com sua equipe de conta da Anthropic.
• Uma destas credenciais:
  • Uma chave de Admin API.
  • Um token bearer OAuth com o escopo org:admin.
  • Uma chave pessoal ou de conta de serviço 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.

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

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

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

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

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.

client = anthropic.Anthropic()

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

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

Sem endpoints, a API retorna uma lista vazia:

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

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)

A resposta é o novo endpoint, conforme mostrado em Campos do endpoint, mais seu signing_secret.

Erros

Uma solicitação retorna um 400 se:

• Sua url não atende às regras em Campos do endpoint, 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. 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. 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.

Compatibility