--- title: Подписка на вебхуки url: https://platform.claude.com/docs/ru/managed-agents/webhooks description: Получайте уведомления о важных событиях без опроса. featureMetadata: topic: title: Managed Agents url: https://platform.claude.com/docs/en/managed-agents/overview status: beta betaHeader: managed-agents-2026-04-01 --- Сессии — это длительные взаимодействия. Хотя большинство взаимодействий в реальном времени происходит через [поток событий SSE](https://platform.claude.com/docs/ru/managed-agents/events-and-streaming), «webhooks» (вебхуки) уведомляют вас о важных изменениях состояния. События вебхуков возвращают `type` и `id` события, а не полный объект. Получив событие вебхука, вам нужно запросить объект напрямую с помощью вызова `GET`. Это позволяет избежать доставки устаревших данных при повторных попытках и сохраняет каждую доставку небольшой. ## Поддерживаемые типы событий Некоторые из этих событий называются иначе, чем соответствующие события в [потоке событий](https://platform.claude.com/docs/ru/managed-agents/events-and-streaming) сессии. Например, событиям потока `session.status_idle` и `session.status_running` соответствуют события вебхуков `session.status_idled` и `session.status_run_started`. | Событие | Триггер | | ---------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `session.status_run_started` | Началось выполнение агента. Срабатывает при каждом переходе статуса сессии в `running`. | | `session.status_idled` | Агент ожидает ввода, например одобрения разрешения на использование инструмента или нового сообщения пользователя. | | `session.budget_reached` | Сессия достигла своего [бюджета](https://platform.claude.com/docs/ru/managed-agents/budgets) и приостановлена. Срабатывает не более одного раза для каждого установленного вами значения бюджета; изменение бюджета снова активирует его. | | `session.status_rescheduled` | Произошла временная ошибка, и сессия автоматически выполняет повторную попытку. | | `session.status_terminated` | Сессия завершена либо из-за неустранимой ошибки, либо потому, что она была архивирована. | | `session.thread_created` | Открыт новый [многоагентный поток](https://platform.claude.com/docs/ru/managed-agents/session-threads): дополнительный агент, вызванный агентом, которого запускает сессия, начинает работу, или происходит консультация с [советником](https://platform.claude.com/docs/ru/managed-agents/multiagent-orchestration#give-the-session-an-advisor) сессии. Оно также срабатывает для каждого потока [запуска рабочего процесса](https://platform.claude.com/docs/ru/managed-agents/workflow-runs#a-runs-threads), как и два других события потоков в этой таблице. | | `session.thread_idled` | Агент в [многоагентном взаимодействии](https://platform.claude.com/docs/ru/managed-agents/session-threads) ожидает ввода. | | `session.thread_terminated` | [Многоагентный поток](https://platform.claude.com/docs/ru/managed-agents/session-threads) завершён либо потому, что поток был архивирован, либо потому, что он исчерпал свои повторные попытки. Субагент, завершивший свою работу, переходит в `idle`, а не в `terminated` (поток советника завершается после окончания консультации, а потоки запуска рабочего процесса завершаются, когда сервер архивирует их к концу запуска). Срабатывает только для дочерних потоков; завершение основного потока, включая архивирование всей сессии, проявляется только как `session.status_terminated`. | | `session.outcome_evaluation_ended` | Завершена [оценка результата](https://platform.claude.com/docs/ru/managed-agents/define-outcomes) для одной итерации. | | `session.updated` | Изменились свойства сессии (например, было обновлено её имя или конфигурация). | | `session.deleted` | Сессия окончательно удалена. Объекта для запроса больше нет, поэтому считайте само событие окончательным. | | Событие | Триггер | | --------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `vault.created` | Хранилище создано. | | `vault.archived` | Хранилище архивировано. Для каждых базовых учётных данных также генерируется событие `vault_credential.archived`. | | `vault.deleted` | Хранилище удалено. Для каждых базовых учётных данных также генерируется событие `vault_credential.deleted`. Объекта для запроса больше нет, поэтому считайте само событие окончательным. | | `vault_credential.created` | Учётные данные созданы. | | `vault_credential.archived` | Учётные данные архивированы — напрямую или в результате архивирования хранилища. | | `vault_credential.deleted` | Учётные данные удалены — напрямую или в результате удаления хранилища. Объекта для запроса больше нет, поэтому считайте само событие окончательным. | | `vault_credential.refresh_failed` | Учётные данные `mcp_oauth` не удаётся обновить (недействительный токен обновления или неустранимая ошибка сервера OAuth). | Эти события отслеживают жизненный цикл ресурсов агентов в вашем рабочем пространстве и отличаются от событий агентов, доставляемых в потоке событий сессии. | Событие | Триггер | | ---------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `agent.created` | Агент создан. | | `agent.updated` | Опубликована [новая версия агента](https://platform.claude.com/docs/ru/managed-agents/agent-setup#update-an-agent). Обновления, не создающие новую версию, не вызывают это событие. | | `agent.archived` | Агент архивирован. | | `agent.deleted` | Агент окончательно удалён. Объекта для запроса больше нет, поэтому считайте само событие окончательным. | | Событие | Триггер | | --------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `deployment.created` | Создано [развёртывание по расписанию](https://platform.claude.com/docs/ru/managed-agents/scheduled-deployments). | | `deployment.updated` | Изменились свойства развёртывания (например, было обновлено его расписание). | | `deployment.paused` | Развёртывание приостановлено — по запросу или автоматически, когда запуск по расписанию завершается неустранимой ошибкой, например из-за архивированного субагента или архивированного окружения. Устранимые сбои, включая ограничения скорости, не приостанавливают развёртывание. См. [Поведение при сбоях](https://platform.claude.com/docs/ru/managed-agents/scheduled-deployments#failure-behavior). | | `deployment.unpaused` | Развёртывание возобновлено, его расписание снова действует. | | `deployment.archived` | Развёртывание архивировано — напрямую или потому, что был архивирован его агент. Если вместо этого агент удалён, развёртывание по расписанию архивируется при следующем запланированном запуске; развёртывание без расписания автоматически не архивируется. | | `deployment.deleted` | Развёртывание окончательно удалено. Объекта для запроса больше нет, поэтому считайте само событие окончательным. | | Событие | Триггер | | -------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `deployment_run.started` | Начался запуск по расписанию. События `deployment_run` генерируют только запуски по расписанию; [ручные запуски](https://platform.claude.com/docs/ru/managed-agents/scheduled-deployments#trigger-a-manual-run) их не генерируют. | | `deployment_run.succeeded` | Запуск по расписанию создал свою сессию. Событие содержит тот же `data.id` (ID запуска), что и событие `deployment_run.started` этого запуска. Чтобы следить за работой сессии, подпишитесь на её события сессии (вкладка «События сессий») или запросите [запуск развёртывания](https://platform.claude.com/docs/ru/managed-agents/scheduled-deployments#deployment-runs), чтобы получить его `session_id` (java: `sessionId`; php: `sessionID`; csharp, go: `SessionID`). | | `deployment_run.failed` | Запуск по расписанию не создал сессию. Событие содержит тот же `data.id`, что и событие `deployment_run.started` этого запуска. Запросите [запуск развёртывания](https://platform.claude.com/docs/ru/managed-agents/scheduled-deployments#deployment-runs), чтобы получить сведения об ошибке. | | Событие | Триггер | | ---------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- | | `environment.created` | Окружение создано. | | `environment.updated` | Окружение обновлено, изменено хотя бы одно поле. Обновление без изменений ничего не генерирует. | | `environment.archived` | Окружение архивировано. Повторное архивирование уже архивированного окружения ничего не генерирует. | | `environment.deleted` | Окружение удалено, включая удаление уже архивированного окружения. Объекта для запроса больше нет, поэтому считайте само событие окончательным. | [Рабочие элементы](https://platform.claude.com/docs/ru/managed-agents/self-hosted-sandboxes) окружения не генерируют событий вебхуков. | Событие | Триггер | | ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `memory_store.created` | Хранилище памяти создано — вами или управляемым Anthropic процессом, который клонирует одно из ваших существующих хранилищ. | | `memory_store.archived` | Хранилище памяти архивировано. Повторное архивирование уже архивированного хранилища ничего не генерирует. | | `memory_store.deleted` | Хранилище памяти удалено, включая удаление уже архивированного хранилища. Удаление хранилища каскадно распространяется на его записи памяти и их версии без генерации событий для каждой записи; сигналом служит единственное событие `memory_store.deleted`. Объекта для запроса больше нет, поэтому считайте само событие окончательным. | Отдельные [записи памяти](https://platform.claude.com/docs/ru/managed-agents/memory) и их версии не генерируют событий вебхуков. ## Регистрация конечной точки В Claude Console перейдите на страницу [Webhooks](https://platform.claude.com/settings/workspaces/default/webhooks) (`platform.claude.com/settings/workspaces/default/webhooks`). Каждая конечная точка принадлежит одному рабочему пространству. Выберите нужное рабочее пространство в селекторе рабочих пространств на боковой панели. Конечная точка вебхука состоит из: * **URL:** должен использовать HTTPS на порту 443 с публично разрешаемым именем хоста. * **Типы событий:** список значений `data.type`, которые получает эта конечная точка. Конечная точка получает только те события, на которые она подписана. * **Секрет подписи:** 32-байтовый секрет с префиксом `whsec_`, генерируемый при создании. Он показывается только один раз, поэтому надёжно сохраните его для проверки доставок вебхуков. ## Проверка подписи Каждая доставка содержит заголовки `webhook-id`, `webhook-timestamp` и `webhook-signature`. Используйте вспомогательный метод SDK `unwrap()` (csharp, go: `Unwrap()`), чтобы проверить подпись и разобрать событие за один шаг. Он выбрасывает исключение, если подпись недействительна или полезная нагрузка старше 5 минут. Установите в `ANTHROPIC_WEBHOOK_SIGNING_KEY` секрет с префиксом `whsec_`, показанный при создании конечной точки. ```python Python 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 ``` ```typescript TypeScript import express from "express"; import Anthropic from "@anthropic-ai/sdk"; const client = new Anthropic(); // reads ANTHROPIC_WEBHOOK_SIGNING_KEY from env const app = express(); // ВАЖНО: используйте express.raw(), а не express.json(). Подпись вычисляется по сырым байтам. app.post("/webhook", express.raw({ type: "application/json" }), (req, res) => { let event; try { // unwrap() выбрасывает исключение, если подпись недействительна или полезная нагрузка устарела event = client.beta.webhooks.unwrap(req.body.toString("utf8"), { headers: req.headers as Record }); } catch { return res.status(400).send("invalid signature"); } switch (event.data.type) { case "session.status_idled": console.log("session idled:", event.data.id); break; // обработка других типов событий } res.sendStatus(200); }); ``` ```csharp C# using Anthropic; var client = new AnthropicClient(); // reads ANTHROPIC_WEBHOOK_SIGNING_KEY from env var app = WebApplication.Create(args); app.MapPost("/webhook", async (HttpRequest request) => { using var reader = new StreamReader(request.Body); var body = await reader.ReadToEndAsync(); var headers = request.Headers.ToDictionary(header => header.Key, header => header.Value.ToString()); UnwrapWebhookEvent webhookEvent; try { // Unwrap() выбрасывает исключение, если подпись недействительна или полезная нагрузка устарела webhookEvent = client.Beta.Webhooks.Unwrap(body, headers); } catch { return Results.BadRequest("invalid signature"); } if (webhookEvent.Data.TryPickSessionStatusIdled(out var idled)) { Console.WriteLine($"session idled: {idled.ID}"); } // обработка других типов событий return Results.Ok(); }); ``` ```go Go package main import ( "fmt" "io" "net/http" "github.com/anthropics/anthropic-sdk-go" ) var client = anthropic.NewClient() // reads ANTHROPIC_WEBHOOK_SIGNING_KEY from env func webhook(w http.ResponseWriter, r *http.Request) { body, err := io.ReadAll(r.Body) if err != nil { http.Error(w, "could not read body", http.StatusBadRequest) return } // Unwrap возвращает ошибку, если подпись недействительна или полезная нагрузка устарела event, err := client.Beta.Webhooks.Unwrap(body, r.Header) if err != nil { http.Error(w, "invalid signature", http.StatusBadRequest) return } switch event.Data.Type { case "session.status_idled": fmt.Println("session idled:", event.Data.ID) // обработка других типов событий } w.WriteHeader(http.StatusOK) } func main() { http.HandleFunc("/webhook", webhook) } ``` ```java Java import com.anthropic.client.AnthropicClient; import com.anthropic.client.okhttp.AnthropicOkHttpClient; import com.anthropic.core.UnwrapWebhookParams; import com.anthropic.core.http.Headers; import com.sun.net.httpserver.HttpServer; // считывает ANTHROPIC_WEBHOOK_SIGNING_KEY из переменных окружения AnthropicClient client = AnthropicOkHttpClient.fromEnv(); void main() throws Exception { var server = HttpServer.create(new InetSocketAddress(8000), 0); server.createContext("/webhook", exchange -> { var body = new String(exchange.getRequestBody().readAllBytes()); var headers = Headers.builder(); exchange.getRequestHeaders().forEach(headers::put); try { // unwrap() выбрасывает исключение, если подпись недействительна или полезная нагрузка устарела var event = client.beta().webhooks().unwrap( UnwrapWebhookParams.builder() .body(body) .headers(headers.build()) .build()); event.data().sessionStatusIdled().ifPresent(idled -> IO.println("session idled: " + idled.id())); // обработка других типов событий exchange.sendResponseHeaders(200, -1); } catch (Exception _) { exchange.sendResponseHeaders(400, -1); } exchange.close(); }); } ``` ```php PHP use Anthropic\Client; use Anthropic\Core\Exceptions\WebhookException; $client = new Client(); // reads ANTHROPIC_WEBHOOK_SIGNING_KEY from env $body = file_get_contents('php://input'); $headers = getallheaders(); try { // unwrap() выбрасывает исключение, если подпись недействительна или полезная нагрузка устарела $event = $client->beta->webhooks->unwrap($body, headers: $headers); } catch (WebhookException) { http_response_code(400); exit('invalid signature'); } match ($event->data->type) { 'session.status_idled' => print "session idled: {$event->data->id}\n", // обработка других типов событий default => null, }; http_response_code(200); ``` ```ruby Ruby require "sinatra" require "anthropic" client = Anthropic::Client.new # reads ANTHROPIC_WEBHOOK_SIGNING_KEY from env post "/webhook" do headers = request.env .select { |key, _| key.start_with?("HTTP_") } .transform_keys { it.delete_prefix("HTTP_").downcase.tr("_", "-") } begin # unwrap выбрасывает исключение, если подпись недействительна или полезная нагрузка устарела event = client.beta.webhooks.unwrap(request.body.read, headers: headers) rescue StandardError halt 400, "invalid signature" end if event.data.type == :"session.status_idled" puts "session idled: #{event.data.id}" end # обработка других типов событий status 200 end ``` ## Обработка события Разберите тело запроса, выполните ветвление по `data.type` и запросите ресурс по ID. Верните любой код `2xx` для подтверждения. Любой другой ответ засчитывается против конечной точки: `3xx` немедленно отключает её (перенаправления никогда не выполняются), а при других сбоях выполняются повторные попытки; правила повторных попыток и автоматического отключения см. в разделе [Поведение доставки](https://platform.claude.com/docs/ru/managed-agents/webhooks#delivery-behavior). Полезная нагрузка каждого события имеет одинаковую структуру, включающую тип события, идентификатор и временную метку момента, когда произошло событие. ```json { "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-..." } } ``` ```python Python if event.data.type == "session.status_idled": session = client.beta.sessions.retrieve(event.data.id) notify_user(session) return "", 204 ``` ```typescript TypeScript if (event.data.type === "session.status_idled") { const session = await client.beta.sessions.retrieve(event.data.id); notifyUser(session); } res.sendStatus(204); ``` ```csharp C# if (webhookEvent.Data.TryPickSessionStatusIdled(out var idled)) { var session = await client.Beta.Sessions.Retrieve(idled.ID); NotifyUser(session); } return Results.StatusCode(204); ``` ```go Go if event.Data.Type == "session.status_idled" { session, err := client.Beta.Sessions.Get(r.Context(), event.Data.ID, anthropic.BetaSessionGetParams{}) if err != nil { panic(err) } notifyUser(session) } w.WriteHeader(http.StatusNoContent) ``` ```java Java event.data().sessionStatusIdled().ifPresent(idled -> { var session = client.beta().sessions().retrieve(idled.id()); notifyUser(session); }); exchange.sendResponseHeaders(204, -1); ``` ```php PHP if ($event->data->type === 'session.status_idled') { $session = $client->beta->sessions->retrieve($event->data->id); notifyUser($session); } http_response_code(204); ``` ```ruby Ruby if event.data.type == :"session.status_idled" session = client.beta.sessions.retrieve(event.data.id) notify_user(session) end status 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` (java, php: `createdAt`; csharp, go: `CreatedAt`) из полезной нагрузки события. * **Автоматическое отключение:** конечная точка автоматически переводится в состояние `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 после устранения проблемы. События, сгенерированные, пока конечная точка была отключена, повторно не доставляются.