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

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

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



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



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

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

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

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



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

Каждая доставка содержит заголовки webhook-id, webhook-timestamp и webhook-signature. Используйте вспомогательную функцию unwrap() из SDK, чтобы проверить подпись и разобрать событие за один шаг. Она выбрасывает исключение, если подпись недействительна или полезная нагрузка старше 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 и получите ресурс по идентификатору. Верните любой код 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 после устранения проблемы. События, сгенерированные во время отключения конечной точки, не воспроизводятся повторно.