--- title: Inscrever-se em webhooks url: https://platform.claude.com/docs/pt-BR/managed-agents/webhooks description: Seja notificado quando eventos importantes acontecerem, sem precisar fazer polling. featureMetadata: topic: title: Managed Agents url: https://platform.claude.com/docs/en/managed-agents/overview status: beta betaHeader: managed-agents-2026-04-01 --- Sessões são interações de longa duração. Embora a maioria das interações em tempo real aconteça por meio do [fluxo de eventos SSE](https://platform.claude.com/docs/pt-BR/managed-agents/events-and-streaming), os webhooks notificam você sobre mudanças de estado importantes. Os eventos de webhook retornam o `type` e o `id` do evento, não o objeto completo. Ao receber um evento de webhook, você precisa buscar o objeto diretamente com uma chamada `GET`. Isso evita a entrega de dados desatualizados em novas tentativas e mantém cada entrega pequena. ## Tipos de eventos suportados Alguns desses eventos têm nomes diferentes dos eventos correspondentes no [fluxo de eventos](https://platform.claude.com/docs/pt-BR/managed-agents/events-and-streaming) da sessão. Por exemplo, `session.status_idle` e `session.status_running` do fluxo correspondem aos eventos de webhook `session.status_idled` e `session.status_run_started`. | Evento | Gatilho | | ---------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `session.status_run_started` | A execução do agente foi iniciada. Isso é acionado a cada transição de status da sessão para `running`. | | `session.status_idled` | O agente está aguardando entrada, por exemplo, uma aprovação de permissão de ferramenta ou uma nova mensagem do usuário. | | `session.budget_reached` | A sessão atingiu seu [orçamento](https://platform.claude.com/docs/pt-BR/managed-agents/budgets) e foi pausada. É disparado no máximo uma vez para cada valor de orçamento que você definir; alterar o orçamento o arma novamente. | | `session.status_rescheduled` | Ocorreu um erro transitório e a sessão está tentando novamente de forma automática. | | `session.status_terminated` | A sessão foi encerrada, seja por causa de um erro irrecuperável ou porque foi arquivada. | | `session.thread_created` | Uma nova [thread multiagente](https://platform.claude.com/docs/pt-BR/managed-agents/session-threads) foi aberta: um agente adicional chamado pelo agente que a sessão executa está começando a trabalhar, ou o [advisor](https://platform.claude.com/docs/pt-BR/managed-agents/multiagent-orchestration#give-the-session-an-advisor) da sessão está sendo consultado. Também é disparado para cada thread de uma [execução de workflow](https://platform.claude.com/docs/pt-BR/managed-agents/workflow-runs#a-runs-threads), assim como os outros dois eventos de thread nesta tabela. | | `session.thread_idled` | Um agente em uma [interação multiagente](https://platform.claude.com/docs/pt-BR/managed-agents/session-threads) está aguardando entrada. | | `session.thread_terminated` | Uma [thread multiagente](https://platform.claude.com/docs/pt-BR/managed-agents/session-threads) foi encerrada, seja porque a thread foi arquivada ou porque esgotou suas novas tentativas. Um subagente que termina seu trabalho passa para `idle`, não `terminated` (uma thread de advisor é encerrada assim que sua consulta é concluída, e as threads de uma execução de workflow são encerradas quando o servidor as arquiva, até o fim da execução). É disparado apenas para threads filhas; o fim da thread principal, incluindo o arquivamento da sessão inteira, aparece apenas como `session.status_terminated`. | | `session.outcome_evaluation_ended` | A [avaliação de resultado](https://platform.claude.com/docs/pt-BR/managed-agents/define-outcomes) de uma única iteração foi concluída. | | `session.updated` | As propriedades da sessão foram alteradas (por exemplo, seu nome ou configuração foi atualizado). | | `session.deleted` | A sessão foi excluída permanentemente. Não há mais objeto para buscar, então trate o próprio evento como final. | | Evento | Gatilho | | --------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `vault.created` | Vault criado. | | `vault.archived` | Vault arquivado. Um evento `vault_credential.archived` também é emitido para cada credencial subjacente. | | `vault.deleted` | Vault excluído. Um evento `vault_credential.deleted` também é emitido para cada credencial subjacente. Não há mais objeto para buscar, então trate o próprio evento como final. | | `vault_credential.created` | Credencial criada. | | `vault_credential.archived` | Credencial arquivada, seja diretamente ou como resultado do arquivamento do vault. | | `vault_credential.deleted` | Credencial excluída, seja diretamente ou como resultado da exclusão do vault. Não há mais objeto para buscar, então trate o próprio evento como final. | | `vault_credential.refresh_failed` | Uma credencial `mcp_oauth` não pode ser renovada (refresh token inválido ou erro irrecuperável do servidor OAuth). | Esses eventos acompanham o ciclo de vida dos recursos de agente no seu workspace e são distintos dos eventos de agente entregues no fluxo de eventos de uma sessão. | Evento | Gatilho | | ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `agent.created` | Agente criado. | | `agent.updated` | Uma [nova versão do agente](https://platform.claude.com/docs/pt-BR/managed-agents/agent-setup#update-an-agent) foi publicada. Atualizações que não criam uma nova versão não acionam este evento. | | `agent.archived` | Agente arquivado. | | `agent.deleted` | Agente excluído permanentemente. Não há mais objeto para buscar, então trate o próprio evento como final. | | Evento | Gatilho | | --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `deployment.created` | [Deployment agendado](https://platform.claude.com/docs/pt-BR/managed-agents/scheduled-deployments) criado. | | `deployment.updated` | As propriedades do deployment foram alteradas (por exemplo, seu agendamento foi atualizado). | | `deployment.paused` | Deployment pausado, seja por solicitação ou automaticamente quando uma execução agendada falha com um erro irrecuperável, como um subagente arquivado ou um ambiente arquivado. Falhas recuperáveis, incluindo limites de taxa, não pausam o deployment. Consulte [Comportamento em caso de falha](https://platform.claude.com/docs/pt-BR/managed-agents/scheduled-deployments#failure-behavior). | | `deployment.unpaused` | Deployment despausado, retomando seu agendamento. | | `deployment.archived` | Deployment arquivado, seja diretamente ou porque seu agente foi arquivado. Se, em vez disso, o agente for excluído, um deployment agendado é arquivado em sua próxima execução agendada; um deployment sem agendamento não é arquivado automaticamente. | | `deployment.deleted` | Deployment excluído permanentemente. Não há mais objeto para buscar, então trate o próprio evento como final. | | Evento | Gatilho | | -------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `deployment_run.started` | Uma execução agendada foi iniciada. Apenas execuções agendadas emitem eventos `deployment_run`; [execuções manuais](https://platform.claude.com/docs/pt-BR/managed-agents/scheduled-deployments#trigger-a-manual-run) não. | | `deployment_run.succeeded` | Uma execução agendada criou sua sessão. O evento carrega o mesmo `data.id` (o ID da execução) que o evento `deployment_run.started` da execução. Para acompanhar o trabalho da sessão, inscreva-se nos eventos dessa sessão (a aba Eventos de sessão) ou busque a [execução de deployment](https://platform.claude.com/docs/pt-BR/managed-agents/scheduled-deployments#deployment-runs) para obter seu `session_id` (java: `sessionId`; php: `sessionID`; csharp, go: `SessionID`). | | `deployment_run.failed` | Uma execução agendada não criou uma sessão. O evento carrega o mesmo `data.id` que o evento `deployment_run.started` da execução. Busque a [execução de deployment](https://platform.claude.com/docs/pt-BR/managed-agents/scheduled-deployments#deployment-runs) para obter os detalhes do erro. | | Evento | Gatilho | | ---------------------- | --------------------------------------------------------------------------------------------------------------------------------------------- | | `environment.created` | Ambiente criado. | | `environment.updated` | Ambiente atualizado com pelo menos um campo alterado. Uma atualização sem efeito não emite nada. | | `environment.archived` | Ambiente arquivado. Arquivar novamente um ambiente já arquivado não emite nada. | | `environment.deleted` | Ambiente excluído, incluindo a exclusão de um ambiente já arquivado. Não há mais objeto para buscar, então trate o próprio evento como final. | Os [itens de trabalho](https://platform.claude.com/docs/pt-BR/managed-agents/self-hosted-sandboxes) de um ambiente não emitem eventos de webhook. | Evento | Gatilho | | ----------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `memory_store.created` | Memory store criado, seja por você ou por um processo operado pela Anthropic que clona um dos seus stores existentes. | | `memory_store.archived` | Memory store arquivado. Arquivar novamente um store já arquivado não emite nada. | | `memory_store.deleted` | Memory store excluído, incluindo a exclusão de um store já arquivado. A exclusão de um store se propaga para suas memórias e versões de memória sem emitir eventos por memória; o único evento `memory_store.deleted` é o sinal. Não há mais objeto para buscar, então trate o próprio evento como final. | [Memórias](https://platform.claude.com/docs/pt-BR/managed-agents/memory) individuais e versões de memória não emitem eventos de webhook. ## Registrar um endpoint No Claude Console, acesse a página [Webhooks](https://platform.claude.com/settings/workspaces/default/webhooks) (`platform.claude.com/settings/workspaces/default/webhooks`). Cada endpoint pertence a um workspace. Selecione o workspace desejado no seletor de workspace na barra lateral. Um endpoint de webhook consiste em: * **URL:** Deve ser HTTPS na porta 443 com um hostname publicamente resolvível. * **Tipos de evento:** A lista de valores de `data.type` que este endpoint recebe. Um endpoint recebe apenas os eventos nos quais está inscrito. * **Segredo de assinatura:** Um segredo de 32 bytes com prefixo `whsec_` gerado na criação. Ele é exibido apenas uma vez, então armazene-o com segurança para verificar as entregas de webhook. ## Verificar a assinatura Toda entrega carrega os cabeçalhos `webhook-id`, `webhook-timestamp` e `webhook-signature`. Use o helper `unwrap()` (csharp, go: `Unwrap()`) do SDK para verificar a assinatura e fazer o parse do evento em uma única etapa. Ele lança uma exceção se a assinatura for inválida ou se o payload tiver mais de 5 minutos. Defina `ANTHROPIC_WEBHOOK_SIGNING_KEY` como o segredo com prefixo `whsec_` exibido na criação do endpoint. ```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() lança uma exceção se a assinatura for inválida ou o payload estiver desatualizado 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) # trata outros tipos de evento 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(); // IMPORTANTE: use express.raw(), não express.json(). A assinatura é calculada sobre os bytes brutos. app.post("/webhook", express.raw({ type: "application/json" }), (req, res) => { let event; try { // unwrap() lança um erro se a assinatura for inválida ou o payload estiver desatualizado 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; // trate outros tipos de evento } 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() lança uma exceção se a assinatura for inválida ou o payload estiver desatualizado 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}"); } // trata outros tipos de evento 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 retorna um erro se a assinatura for inválida ou o payload estiver desatualizado 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) // trata outros tipos de evento } 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; // lê ANTHROPIC_WEBHOOK_SIGNING_KEY do ambiente 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() lança um erro se a assinatura for inválida ou o payload estiver desatualizado 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())); // trata outros tipos de evento 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() lança uma exceção se a assinatura for inválida ou o payload estiver desatualizado $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", // trata outros tipos de evento 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 lança uma exceção se a assinatura for inválida ou o payload estiver desatualizado 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 # trata outros tipos de evento status 200 end ``` ## Tratar um evento Faça o parse do corpo, use um switch em `data.type` e busque o recurso pelo ID. Retorne qualquer `2xx` para confirmar o recebimento. Qualquer outra resposta conta contra o endpoint: um `3xx` o desativa imediatamente (redirecionamentos nunca são seguidos), enquanto outras falhas são tentadas novamente; consulte [Comportamento de entrega](https://platform.claude.com/docs/pt-BR/managed-agents/webhooks#delivery-behavior) para as regras de novas tentativas e de desativação automática. Todo payload de evento tem a mesma estrutura, incluindo o tipo do evento, o identificador e o timestamp de quando o evento ocorreu. ```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 ``` O `event.id` de nível superior é único por evento, não por entrega. Se você receber o mesmo `event.id` duas vezes, trata-se de uma nova tentativa e você pode descartá-lo. ## Comportamento de entrega * **Duplicatas:** Um endpoint pode receber o mesmo evento mais de uma vez, e toda tentativa entrega o mesmo `event.id` de nível superior (o mesmo valor do cabeçalho `webhook-id`). Faça a deduplicação com base nele. * **Escopo de inscrição:** Um evento é entregue apenas aos endpoints inscritos em seu tipo no momento em que ele é emitido. Um evento emitido enquanto nenhum endpoint está inscrito em seu tipo nunca é entregue, e inscrever-se depois não o preenche retroativamente, então inscreva-se em um tipo de evento antes de precisar dele. * **A ordem não é garantida.** Os eventos não são entregues na ordem em que ocorreram: `session.status_idled` pode chegar antes de `session.outcome_evaluation_ended` mesmo que o resultado tenha sido produzido primeiro, e um evento `.deleted` pode chegar antes do evento `.archived` do mesmo recurso. Baseie seu estado no recurso que você busca, não na ordem em que os eventos chegam. * **Novas tentativas:** Para cada endpoint e evento, a Anthropic faz até três tentativas de entrega (uma resposta que aciona a desativação automática, descrita mais adiante nesta seção, nunca é tentada novamente) com backoff exponencial com jitter entre 5 e 120 segundos. Toda tentativa entrega o mesmo `event.id`. Depois que a última tentativa falha, o evento é descartado: ele não é enfileirado para entrega posterior e não há nenhum sinal de que foi perdido. Webhooks não são um log durável, então, se você precisar observar todas as transições, faça a reconciliação listando ou buscando o recurso por meio da API. * **Timestamps:** O cabeçalho `webhook-timestamp` é carimbado quando uma tentativa de entrega é assinada e é regenerado a cada nova tentativa, para que as novas tentativas não sejam rejeitadas pela verificação de atualidade do SDK. Ele é o relógio da tentativa de entrega, não do evento: use o `created_at` (java, php: `createdAt`; csharp, go: `CreatedAt`) do payload do evento para saber quando o evento ocorreu. * **Desativação automática:** Um endpoint é automaticamente definido como `disabled` com um `disabled_reason` legível por máquina em três casos: * O endpoint retorna uma resposta `3xx`. Redirecionamentos nunca são seguidos; isso desativa o endpoint imediatamente, na primeira tentativa, com o motivo `auto-disabled: endpoint URL returned a redirect (3xx)`. Se o seu endpoint mudar de lugar, atualize a URL no Console e reative o endpoint. * A URL do endpoint é resolvida para um endereço IP não público quando a Anthropic se conecta. Isso desativa o endpoint imediatamente, com o motivo `auto-disabled: endpoint URL resolved to an invalid address`. * As entregas para o endpoint falham continuamente por um período prolongado, com o motivo `auto-disabled after sustained delivery failures`. O gatilho é por quanto tempo o endpoint vem falhando sem interrupção, não uma contagem de entregas. Um único `2xx` reinicia a janela, então um evento instável não consegue desativar o endpoint. Os três casos são reversíveis: reative o endpoint no Console depois de resolver o problema. Eventos emitidos enquanto o endpoint estava desativado não são reenviados.