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

Сессии — это длительные взаимодействия. Хотя большинство взаимодействий в реальном времени происходит через поток событий 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 и получите ресурс по идентификатору. Верните любой код 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 после устранения проблемы. События, сгенерированные в период, когда конечная точка была отключена, не воспроизводятся повторно.