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

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

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

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

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

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

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

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

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

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

Установите 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": "event_01ABC...",
  "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 дважды, это повторная попытка, и вы можете её отбросить.

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

• Порядок не гарантируется. session.status_idled может прийти раньше session.outcome_evaluation_ended, даже если результат был получен первым. Используйте временную метку created_at для сортировки, если порядок имеет значение.
• Повторные попытки: Anthropic выполняет повторную попытку как минимум один раз. Повторная попытка доставляет тот же event.id.
• Перенаправления не обрабатываются. Код 3xx рассматривается как ошибка. Если ваша конечная точка переместилась, обновите URL в Console.
• Автоматическое отключение: Конечная точка автоматически переводится в состояние disabled с машиночитаемым disabled_reason примерно после 20 последовательных неудачных доставок или немедленно, если имя хоста разрешается в частный IP-адрес или конечная точка возвращает перенаправление. После устранения проблемы повторно включите её вручную в Console.