Вебхуки организации

«Organization webhook endpoint» (конечная точка вебхука организации) получает событие, когда Anthropic ограничивает или блокирует один из профилей пользователей вашей организации, а также когда ограничение или блокировка завершается. Вы управляете ею с помощью Admin API по пути /v1/organizations/webhooks.

Любой участник вашей организации может просматривать список конечных точек вебхуков организации и отдельные конечные точки через API, но только участники с ролью администратора, владельца или основного владельца могут создавать, изменять или удалять их, а также заменять их секрет подписи.

Перед началом работы

Вам понадобится следующее:

• Организация в Claude API, для которой включены вебхуки организации и не включена готовность к HIPAA. Чтобы запросить доступ, свяжитесь со своей командой по работе с клиентами Anthropic.
• Одни из следующих учётных данных:
  • Ключ Admin API.
  • OAuth bearer-токен с областью действия org:admin.
  • Персональный ключ или ключ сервисного аккаунта, не ограниченный рабочим пространством.

Типы событий

Конечные точки вебхуков организации принимают два типа событий. Оба относятся к «enforcement actions» (мерам воздействия) в отношении профилей пользователей. Мера воздействия — это ограничение или блокировка, которую Anthropic применяет к конечному клиенту, представленному профилем.

Удаление профиля завершает его открытые меры без события user_profile.enforcement_action_resolved.

Перед вашим первым событием

В ваших профилях не будет полей enforcement_status и enforcement_actions, пока для вашей организации не включены меры воздействия. До этого момента, а также в любом запросе, заголовок anthropic-beta которого содержит user-profiles-2026-09-04 или более раннее значение, ответы не включают эти поля, а фильтр списка enforcement_status[] возвращает 400. Чтобы получить эти поля, удалите это значение из своих запросов.

Если мера воздействия была открыта до того, как Anthropic включила меры воздействия и доставку событий для вашей организации, или до того, как вы зарегистрировали свою конечную точку, вы не получите для неё событие user_profile.enforcement_action_opened. Мера всё равно отображается в профиле. Чтобы найти такие меры, получите список своих профилей с параметрами enforcement_status[]=restricted и enforcement_status[]=banned. Ответ может вернуть меньше профилей, чем limit, или ни одного, ещё до окончания списка, поэтому продолжайте запрашивать страницы, пока next_page не станет null.

Что содержит событие

События содержат идентификаторы, а не саму меру или профиль. data.id — это идентификатор профиля, а data.enforcement_action_id — идентификатор меры, который начинается с 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"
  }
}

Чтобы узнать, что изменилось, получите профиль с помощью client.user_profiles.retrieve(), используя data.id. Его список enforcement_actions показывает открытые меры. У каждой меры есть type (restriction или ban), id, reason, время opened_at и время expires_at или null. enforcement_status обобщает их: banned, пока открыта блокировка, restricted, пока открыта любая другая мера, и unrestricted, когда открытых мер нет. Любое другое значение рассматривайте как restricted.

Anthropic отправляет событие только после того, как изменение отразится в профиле, поэтому полученный вами профиль показывает это изменение или более позднее. События могут приходить с задержкой или не по порядку, поэтому ориентируйтесь на текущее состояние профиля, а не на порядок поступления событий. После user_profile.enforcement_action_resolved завершённая мера больше не отображается в списке. Ответ 404 означает, что профиль был удалён.

Поля конечной точки

Конечная точка вебхука организации имеет следующие поля:

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

Организация может иметь до 32 конечных точек вебхуков организации. Отключённые конечные точки вебхуков также учитываются в этом лимите.

Доставки

Доставки соответствуют спецификации Standard Webhooks. Каждая из них содержит заголовки webhook-id, webhook-timestamp и webhook-signature. Прежде чем доверять событию, проверьте его подпись с помощью секрета подписи конечной точки, используя любую библиотеку Standard Webhooks.

Возвращайте любой статус 2xx в течение 5 секунд, а медленную работу выполняйте после этого. Любой другой ответ или отсутствие ответа считается неудачной попыткой.

• Дубликаты: Конечная точка может получить одно и то же событие более одного раза с тем же id события (тем же значением, что и в заголовке webhook-id). Выполняйте дедупликацию по нему.

• Повторные попытки: Если доставка не удалась, Anthropic повторяет её несколько раз в течение следующих нескольких минут. Если все попытки неудачны, Anthropic отбрасывает событие. Чтобы наверстать упущенное, получите список своих профилей по статусу мер воздействия, как описано в разделе Перед вашим первым событием.

• Автоматическое отключение: Anthropic отключает конечную точку, когда:

  • Она возвращает перенаправление (3xx).
  • Её URL разрешается в непубличный IP-адрес.
  • Доставки на неё продолжают завершаться неудачей.

  Anthropic пропускает события для отключённой конечной точки и не отправляет их позже.

Управление конечными точками

С помощью Admin API вы можете выполнять следующие запросы:

При обновлении enabled_events заменяет весь список типов событий конечной точки. Пустой список не очищает список: конечная точка сохраняет имевшиеся у неё типы событий. Чтобы остановить доставки, отправьте "state": "disabled" или удалите конечную точку.

Чтобы снова включить конечную точку, в том числе после того, как Anthropic её отключила, отправьте "state": "enabled" в запросе на обновление.

Когда вы заменяете секрет подписи, старый секрет сразу перестаёт работать. Все последующие доставки, включая повторные попытки доставки более ранних событий, подписываются новым секретом, поэтому немедленно обновите свой обработчик.

Отправляйте заголовок anthropic-beta: webhooks-2026-10-07 с каждым запросом. SDK и CLI отправляют его за вас. В этом примере выводится список конечных точек вашей организации с использованием ключа Admin API из ANTHROPIC_API_KEY.

client = anthropic.Anthropic()

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

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

Если конечных точек нет, API возвращает пустой список:

{
  "data": [],
  "has_more": false
}

По умолчанию список возвращает до 20 конечных точек. Установите limit, чтобы получить до 100. Если has_more равно true, передайте last_id из ответа в качестве after_id, чтобы получить следующую страницу.

В этом примере создаётся конечная точка, которая получает оба типа событий:

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)

Ответ содержит новую конечную точку, как показано в разделе Поля конечной точки, а также её signing_secret.

Ошибки

Запрос возвращает 400, если:

• Его url не соответствует правилам из раздела Поля конечной точки, или запрос на создание не содержит ни одного типа событий. В сообщении об ошибке указано, что не так.
• У вашей организации нет рабочего пространства по умолчанию.
• Вебхуки организации недоступны для вашей организации, поскольку её рабочее пространство по умолчанию использует ключ шифрования, управляемый клиентом. Об этом говорится в сообщении об ошибке.
• Он привёл бы к тому, что у вашей организации будет более 32 конечных точек вебхуков организации.
• Он указывает в enabled_events тип события, отличный от двух, перечисленных в разделе Типы событий. В сообщении об ошибке перечислены допустимые типы.

Запрос возвращает 403, если роль вашего аккаунта не включает разрешение, необходимое для запроса. В ошибке указывается это разрешение.

Запрос возвращает 404, если:

• Он не отправляет заголовок anthropic-beta: webhooks-2026-10-07.
• Anthropic не включила вебхуки организации для вашей организации.
• Для вашей организации включена готовность к HIPAA.
• Он использует тип учётных данных, который эти запросы не принимают.
• Его webhook_endpoint_id не соответствует ни одной конечной точке в вашей организации.

Запрос возвращает 409, если:

• Он привёл бы к тому, что две включённые конечные точки вебхуков организации будут иметь один и тот же URL.
• Другой запрос одновременно изменил конечные точки вашей организации. Повторите запрос.

Compatibility