Подписка на вебхуки

Сессии — это длительные взаимодействия. Хотя большинство взаимодействий в реальном времени происходит через поток событий SSE, «webhooks» (вебхуки) уведомляют вас о важных изменениях состояния.

События вебхуков возвращают type и id события, а не полный объект. Получив событие вебхука, вам нужно запросить объект напрямую с помощью вызова GET. Это позволяет избежать доставки устаревших данных при повторных попытках и сохраняет каждую доставку небольшой.

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

Регистрация конечной точки

Перейдите в раздел Manage > Webhooks в Claude Console.

Конечная точка вебхука состоит из:

• URL: должен использовать HTTPS на порту 443 с публично разрешаемым именем хоста.
• Типы событий: список значений data.type, которые получает эта конечная точка. Конечная точка получает только те события, на которые она подписана.
• Секрет подписи: 32-байтовый секрет с префиксом whsec_, генерируемый при создании. Он показывается только один раз, поэтому надёжно сохраните его для проверки доставок вебхуков.

Проверка подписи

Каждая доставка содержит заголовки webhook-id, webhook-timestamp и webhook-signature. Используйте вспомогательный метод SDK unwrap(), чтобы проверить подпись и разобрать событие за один шаг. Он выбрасывает исключение, если подпись недействительна или полезная нагрузка старше 5 минут.

Установите в ANTHROPIC_WEBHOOK_SIGNING_KEY секрет с префиксом whsec_, показанный при создании конечной точки.

from flask import Flask, request
import anthropic

client = anthropic.Anthropic()  # reads ANTHROPIC_WEBHOOK_SIGNING_KEY from env
app = Flask(__name__)


@app.route("/webhook", methods=["POST"])
def webhook():
    try:
        # unwrap() выбрасывает исключение, если подпись недействительна или полезная нагрузка устарела
        event = client.beta.webhooks.unwrap(
            request.get_data(as_text=True),
            headers=dict(request.headers),
        )
    except Exception:
        return "invalid signature", 400

    if event.data.type == "session.status_idled":
        print("session idled:", event.data.id)
    # обработка других типов событий

    return "", 200

Обработка события

Разберите тело запроса, выполните ветвление по data.type и запросите ресурс по ID. Верните любой код 2xx для подтверждения. Любой другой ответ засчитывается против конечной точки: 3xx немедленно отключает её (перенаправления никогда не выполняются), а при других сбоях выполняются повторные попытки; правила повторных попыток и автоматического отключения см. в разделе Поведение доставки.

Полезная нагрузка каждого события имеет одинаковую структуру, включающую тип события, идентификатор и временную метку момента, когда произошло событие.

{
  "type": "event",
  "id": "whe_9d5c1f7e...",
  "created_at": "2026-03-18T14:05:22Z",
  "data": {
    "type": "session.status_idled",
    "id": "sesn_01XYZ...",
    "organization_id": "8a3d2f1e-...",
    "workspace_id": "c7b0e4d9-..."
  }
}

if event.data.type == "session.status_idled":
    session = client.beta.sessions.retrieve(event.data.id)
    notify_user(session)
return "", 204

Верхнеуровневый event.id уникален для каждого события, а не для каждой доставки. Если вы получили один и тот же event.id дважды, это повторная попытка, и её можно отбросить.

Поведение доставки

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

• Область подписки: событие доставляется только конечным точкам, подписанным на его тип в момент его генерации. Событие, сгенерированное, когда ни одна конечная точка не подписана на его тип, никогда не доставляется, и последующая подписка не восполняет его, поэтому подписывайтесь на тип события до того, как он вам понадобится.

• Порядок не гарантируется. События доставляются не в том порядке, в котором они произошли: session.status_idled может прийти раньше session.outcome_evaluation_ended, даже если результат был получен первым, а событие .deleted может прийти раньше события .archived для того же ресурса. Определяйте состояние по запрашиваемому ресурсу, а не по порядку поступления событий.

• Повторные попытки: для каждой конечной точки и каждого события Anthropic выполняет до трёх попыток доставки (ответ, вызывающий автоматическое отключение, описанное далее в этом разделе, никогда не повторяется) с экспоненциальной задержкой со случайным разбросом от 5 до 120 секунд. Каждая попытка доставляет один и тот же event.id. После неудачи последней попытки событие отбрасывается: оно не ставится в очередь для последующей доставки, и нет никакого сигнала о его потере. Вебхуки не являются надёжным журналом, поэтому, если вам нужно отслеживать каждый переход, выполняйте сверку, получая список ресурсов или запрашивая ресурс через API.

• Временные метки: заголовок webhook-timestamp проставляется при подписании попытки доставки и генерируется заново при каждой повторной попытке, поэтому повторные попытки не отклоняются проверкой актуальности в SDK. Это время попытки доставки, а не события: чтобы узнать, когда произошло событие, используйте created_at из полезной нагрузки события.

• Автоматическое отключение: конечная точка автоматически переводится в состояние disabled с машиночитаемым disabled_reason в трёх случаях:

  • Конечная точка возвращает ответ 3xx. Перенаправления никогда не выполняются; это немедленно, при первой же попытке, отключает конечную точку с причиной auto-disabled: endpoint URL returned a redirect (3xx). Если ваша конечная точка переехала, обновите URL в Console и снова включите конечную точку.
  • URL конечной точки разрешается в непубличный IP-адрес при подключении Anthropic. Это немедленно отключает конечную точку с причиной auto-disabled: endpoint URL resolved to an invalid address.
  • Доставки на конечную точку непрерывно завершаются неудачей в течение длительного периода; причина — auto-disabled after sustained delivery failures. Триггером служит продолжительность непрерывных сбоев конечной точки, а не количество доставок. Один ответ 2xx сбрасывает окно, поэтому одно нестабильное событие не может отключить конечную точку.

  Все три случая обратимы: снова включите конечную точку в Console после устранения проблемы. События, сгенерированные, пока конечная точка была отключена, повторно не доставляются.