--- title: Suscribirse a webhooks url: https://platform.claude.com/docs/es/managed-agents/webhooks description: Recibe notificaciones cuando ocurran eventos importantes sin necesidad de sondeo. featureMetadata: topic: title: Managed Agents url: https://platform.claude.com/docs/en/managed-agents/overview status: beta betaHeader: managed-agents-2026-04-01 --- Las sesiones son interacciones de larga duración. Aunque la mayoría de las interacciones en tiempo real ocurren a través del [flujo de eventos SSE](https://platform.claude.com/docs/es/managed-agents/events-and-streaming), los "webhooks" (ganchos web) te notifican sobre cambios de estado importantes. Los eventos de webhook devuelven el `type` y el `id` del evento, no el objeto completo. Cuando recibes un evento de webhook, necesitas obtener el objeto directamente con una llamada `GET`. Esto evita entregar datos obsoletos en los reintentos y mantiene cada entrega pequeña. ## Tipos de eventos compatibles Algunos de estos eventos tienen nombres diferentes a los de los eventos correspondientes en el [flujo de eventos](https://platform.claude.com/docs/es/managed-agents/events-and-streaming) de la sesión. Por ejemplo, `session.status_idle` y `session.status_running` del flujo corresponden a los eventos de webhook `session.status_idled` y `session.status_run_started`. | Evento | Desencadenante | | ---------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `session.status_run_started` | Se inició la ejecución del agente. Se desencadena en cada transición del estado de la sesión a `running`. | | `session.status_idled` | El agente está esperando una entrada, por ejemplo, la aprobación de un permiso de herramienta o un nuevo mensaje del usuario. | | `session.budget_reached` | La sesión alcanzó su [presupuesto](https://platform.claude.com/docs/es/managed-agents/budgets) y se pausó. Se dispara como máximo una vez por cada valor de presupuesto que establezcas; cambiar el presupuesto lo vuelve a activar. | | `session.status_rescheduled` | Ocurrió un error transitorio y la sesión está reintentando automáticamente. | | `session.status_terminated` | La sesión terminó, ya sea por un error irrecuperable o porque fue archivada. | | `session.thread_created` | Se abrió un nuevo [hilo multiagente](https://platform.claude.com/docs/es/managed-agents/session-threads): un agente adicional llamado por el agente que ejecuta la sesión está comenzando a trabajar, o se está consultando al [asesor](https://platform.claude.com/docs/es/managed-agents/multiagent-orchestration#give-the-session-an-advisor) de la sesión. También se dispara para cada hilo de una [ejecución de flujo de trabajo](https://platform.claude.com/docs/es/managed-agents/workflow-runs#a-runs-threads), al igual que los otros dos eventos de hilo de esta tabla. | | `session.thread_idled` | Un agente en una [interacción multiagente](https://platform.claude.com/docs/es/managed-agents/session-threads) está esperando una entrada. | | `session.thread_terminated` | Un [hilo multiagente](https://platform.claude.com/docs/es/managed-agents/session-threads) terminó, ya sea porque el hilo fue archivado o porque agotó sus reintentos. Un subagente que termina su trabajo pasa a `idle`, no a `terminated` (un hilo de asesor termina una vez que se completa su consulta, y los hilos de una ejecución de flujo de trabajo terminan cuando el servidor los archiva, al final de la ejecución). Se dispara solo para hilos secundarios; el final del hilo principal, incluido el archivado de toda la sesión, aparece solo como `session.status_terminated`. | | `session.outcome_evaluation_ended` | Se completó la [evaluación de resultados](https://platform.claude.com/docs/es/managed-agents/define-outcomes) para una sola iteración. | | `session.updated` | Cambiaron las propiedades de la sesión (por ejemplo, se actualizó su nombre o configuración). | | `session.deleted` | La sesión se eliminó permanentemente. No queda ningún objeto que obtener, así que trata el evento en sí como definitivo. | | Evento | Desencadenante | | --------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `vault.created` | Se creó la bóveda. | | `vault.archived` | Se archivó la bóveda. También se emite un evento `vault_credential.archived` por cada credencial subyacente. | | `vault.deleted` | Se eliminó la bóveda. También se emite un evento `vault_credential.deleted` por cada credencial subyacente. No queda ningún objeto que obtener, así que trata el evento en sí como definitivo. | | `vault_credential.created` | Se creó la credencial. | | `vault_credential.archived` | Se archivó la credencial, ya sea directamente o como resultado del archivado de la bóveda. | | `vault_credential.deleted` | Se eliminó la credencial, ya sea directamente o como resultado de la eliminación de la bóveda. No queda ningún objeto que obtener, así que trata el evento en sí como definitivo. | | `vault_credential.refresh_failed` | No se puede actualizar una credencial `mcp_oauth` (token de actualización no válido o error irrecuperable del servidor OAuth). | Estos eventos rastrean el ciclo de vida de los recursos de agente en tu espacio de trabajo y son distintos de los eventos de agente entregados en el flujo de eventos de una sesión. | Evento | Desencadenante | | ---------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `agent.created` | Se creó el agente. | | `agent.updated` | Se publicó una [nueva versión del agente](https://platform.claude.com/docs/es/managed-agents/agent-setup#update-an-agent). Las actualizaciones que no crean una nueva versión no desencadenan este evento. | | `agent.archived` | Se archivó el agente. | | `agent.deleted` | El agente se eliminó permanentemente. No queda ningún objeto que obtener, así que trata el evento en sí como definitivo. | | Evento | Desencadenante | | --------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `deployment.created` | Se creó una [implementación programada](https://platform.claude.com/docs/es/managed-agents/scheduled-deployments). | | `deployment.updated` | Cambiaron las propiedades de la implementación (por ejemplo, se actualizó su programación). | | `deployment.paused` | Se pausó la implementación, ya sea por solicitud o automáticamente cuando una ejecución programada falla con un error irrecuperable, como un subagente archivado o un entorno archivado. Los fallos recuperables, incluidos los límites de velocidad, no pausan la implementación. Consulta [Comportamiento ante fallos](https://platform.claude.com/docs/es/managed-agents/scheduled-deployments#failure-behavior). | | `deployment.unpaused` | Se reanudó la implementación, retomando su programación. | | `deployment.archived` | Se archivó la implementación, ya sea directamente o porque su agente fue archivado. Si en cambio el agente se elimina, una implementación programada se archiva en su siguiente ejecución programada; una implementación sin programación no se archiva automáticamente. | | `deployment.deleted` | La implementación se eliminó permanentemente. No queda ningún objeto que obtener, así que trata el evento en sí como definitivo. | | Evento | Desencadenante | | -------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `deployment_run.started` | Se inició una ejecución programada. Solo las ejecuciones programadas emiten eventos `deployment_run`; las [ejecuciones manuales](https://platform.claude.com/docs/es/managed-agents/scheduled-deployments#trigger-a-manual-run) no. | | `deployment_run.succeeded` | Una ejecución programada creó su sesión. El evento lleva el mismo `data.id` (el ID de la ejecución) que el evento `deployment_run.started` de la ejecución. Para seguir el trabajo de la sesión, suscríbete a sus eventos de sesión (la pestaña Eventos de sesión), u obtén la [ejecución de implementación](https://platform.claude.com/docs/es/managed-agents/scheduled-deployments#deployment-runs) para conocer su `session_id` (java: `sessionId`; php: `sessionID`; csharp, go: `SessionID`). | | `deployment_run.failed` | Una ejecución programada no creó una sesión. El evento lleva el mismo `data.id` que el evento `deployment_run.started` de la ejecución. Obtén la [ejecución de implementación](https://platform.claude.com/docs/es/managed-agents/scheduled-deployments#deployment-runs) para ver los detalles del error. | | Evento | Desencadenante | | ---------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `environment.created` | Se creó el entorno. | | `environment.updated` | Se actualizó el entorno con al menos un campo modificado. Una actualización sin cambios no emite nada. | | `environment.archived` | Se archivó el entorno. Volver a archivar un entorno ya archivado no emite nada. | | `environment.deleted` | Se eliminó el entorno, incluida la eliminación de un entorno ya archivado. No queda ningún objeto que obtener, así que trata el evento en sí como definitivo. | Los [elementos de trabajo](https://platform.claude.com/docs/es/managed-agents/self-hosted-sandboxes) de un entorno no emiten eventos de webhook. | Evento | Desencadenante | | ----------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `memory_store.created` | Se creó el almacén de memoria, ya sea por ti o por un proceso operado por Anthropic que clona uno de tus almacenes existentes. | | `memory_store.archived` | Se archivó el almacén de memoria. Volver a archivar un almacén ya archivado no emite nada. | | `memory_store.deleted` | Se eliminó el almacén de memoria, incluida la eliminación de un almacén ya archivado. Eliminar un almacén se propaga en cascada a sus memorias y versiones de memoria sin emitir eventos por memoria; el único evento `memory_store.deleted` es la señal. No queda ningún objeto que obtener, así que trata el evento en sí como definitivo. | Las [memorias](https://platform.claude.com/docs/es/managed-agents/memory) individuales y las versiones de memoria no emiten eventos de webhook. ## Registrar un endpoint En la Claude Console, ve a la página [Webhooks](https://platform.claude.com/settings/workspaces/default/webhooks) (`platform.claude.com/settings/workspaces/default/webhooks`). Cada endpoint pertenece a un espacio de trabajo. Selecciona el espacio de trabajo que quieras en el selector de espacios de trabajo de la barra lateral. Un "endpoint" (punto de conexión) de webhook consta de: * **URL:** Debe ser HTTPS en el puerto 443 con un nombre de host que se pueda resolver públicamente. * **Tipos de eventos:** La lista de valores `data.type` que recibe este endpoint. Un endpoint solo recibe los eventos a los que está suscrito. * **Secreto de firma:** Un secreto de 32 bytes con el prefijo `whsec_` generado en la creación. Se muestra solo una vez, así que guárdalo de forma segura para verificar las entregas de webhooks. ## Verificar la firma Cada entrega incluye los encabezados `webhook-id`, `webhook-timestamp` y `webhook-signature`. Usa el asistente `unwrap()` (csharp, go: `Unwrap()`) del SDK para verificar la firma y analizar el evento en un solo paso. Lanza una excepción si la firma no es válida o si la carga útil tiene más de 5 minutos de antigüedad. Establece `ANTHROPIC_WEBHOOK_SIGNING_KEY` con el secreto con prefijo `whsec_` que se muestra al crear el 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() lanza una excepción si la firma no es válida o el payload está obsoleto 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) # maneja otros tipos de eventos 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: usa express.raw(), no express.json(). La firma se calcula sobre los bytes sin procesar. app.post("/webhook", express.raw({ type: "application/json" }), (req, res) => { let event; try { // unwrap() lanza una excepción si la firma no es válida o el payload está obsoleto 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; // maneja otros tipos de eventos } 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() lanza una excepción si la firma no es válida o el payload está obsoleto 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}"); } // maneja otros tipos de eventos 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 devuelve un error si la firma no es válida o el payload está obsoleto 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) // maneja otros tipos de eventos } 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; // lee ANTHROPIC_WEBHOOK_SIGNING_KEY del entorno 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() lanza una excepción si la firma no es válida o el payload está obsoleto 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())); // maneja otros tipos de eventos 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() lanza una excepción si la firma no es válida o el payload está obsoleto $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", // maneja otros tipos de eventos 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 lanza una excepción si la firma no es válida o el payload está obsoleto 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 # maneja otros tipos de eventos status 200 end ``` ## Manejar un evento Analiza el cuerpo, evalúa `data.type` y obtén el recurso por ID. Devuelve cualquier `2xx` para confirmar la recepción. Cualquier otra respuesta cuenta en contra del endpoint: un `3xx` lo deshabilita inmediatamente (las redirecciones nunca se siguen), mientras que otros fallos se reintentan; consulta [Comportamiento de entrega](https://platform.claude.com/docs/es/managed-agents/webhooks#delivery-behavior) para conocer las reglas de reintento y deshabilitación automática. Cada carga útil de evento tiene la misma estructura, incluidos el tipo de evento, el identificador y la marca de tiempo de cuándo ocurrió el evento. ```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 ``` El `event.id` de nivel superior es único por evento, no por entrega. Si recibes el mismo `event.id` dos veces, es un reintento y puedes descartarlo. ## Comportamiento de entrega * **Duplicados:** Un endpoint puede recibir el mismo evento más de una vez, y cada intento entrega el mismo `event.id` de nivel superior (el mismo valor que el encabezado `webhook-id`). Elimina duplicados basándote en él. * **Alcance de la suscripción:** Un evento se entrega solo a los endpoints suscritos a su tipo en el momento en que se emite. Un evento emitido mientras ningún endpoint está suscrito a su tipo nunca se entrega, y suscribirse más tarde no lo recupera, así que suscríbete a un tipo de evento antes de necesitarlo. * **El orden no está garantizado.** Los eventos no se entregan en el orden en que ocurrieron: `session.status_idled` podría llegar antes que `session.outcome_evaluation_ended` aunque el resultado se haya producido primero, y un evento `.deleted` puede llegar antes que el evento `.archived` del mismo recurso. Basa tu estado en el recurso que obtienes, no en el orden en que llegan los eventos. * **Reintentos:** Para cada endpoint y evento, Anthropic realiza hasta tres intentos de entrega (una respuesta que desencadena la deshabilitación automática, descrita más adelante en esta sección, nunca se reintenta) con un retroceso exponencial con variación aleatoria de entre 5 y 120 segundos. Cada intento entrega el mismo `event.id`. Después de que falla el último intento, el evento se descarta: no se pone en cola para una entrega posterior y no hay ninguna señal de que se haya perdido. Los webhooks no son un registro duradero, así que si necesitas observar cada transición, concilia listando u obteniendo el recurso a través de la API. * **Marcas de tiempo:** El encabezado `webhook-timestamp` se establece cuando se firma un intento de entrega y se regenera en cada reintento, de modo que la comprobación de vigencia del SDK no rechaza los reintentos. Es el reloj del intento de entrega, no del evento: usa el `created_at` (java, php: `createdAt`; csharp, go: `CreatedAt`) de la carga útil del evento para saber cuándo ocurrió el evento. * **Deshabilitación automática:** Un endpoint se establece automáticamente en `disabled` con un `disabled_reason` legible por máquina en tres casos: * El endpoint devuelve una respuesta `3xx`. Las redirecciones nunca se siguen; esto deshabilita el endpoint inmediatamente, en el primer intento, con el motivo `auto-disabled: endpoint URL returned a redirect (3xx)`. Si tu endpoint cambia de ubicación, actualiza la URL en la Console y vuelve a habilitar el endpoint. * La URL del endpoint se resuelve en una dirección IP no pública cuando Anthropic se conecta. Esto deshabilita el endpoint inmediatamente, con el motivo `auto-disabled: endpoint URL resolved to an invalid address`. * Las entregas al endpoint fallan continuamente durante un período prolongado, con el motivo `auto-disabled after sustained delivery failures`. El desencadenante es cuánto tiempo lleva fallando el endpoint sin interrupción, no un recuento de entregas. Un solo `2xx` reinicia la ventana, por lo que un evento inestable no puede deshabilitar el endpoint. Los tres casos son reversibles: vuelve a habilitar el endpoint en la Console después de resolver el problema. Los eventos emitidos mientras el endpoint estaba deshabilitado no se vuelven a reproducir.