Suscribirse a webhooks

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, 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

Registrar un endpoint

En la Claude Console, ve a la página 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() 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.

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

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 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.

{
  "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

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 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.