Suscribirse a webhooks

Las sesiones son interacciones de larga duración. Si bien la mayoría de las interacciones en tiempo real ocurren a través del flujo de eventos SSE, los webhooks 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 admitidos



Registrar un endpoint

Visita Manage > Webhooks en la Claude Console.

Un endpoint 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 eventos a los que está suscrito.
• Secreto de firma: Un secreto de 32 bytes con prefijo whsec_ generado en el momento de la creación. Se muestra solo una vez, así que guárdalo de forma segura para verificar las entregas de webhook.



Verificar la firma

Cada entrega lleva los encabezados webhook-id, webhook-timestamp y webhook-signature. Usa el helper 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, haz un switch sobre 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 (nunca se siguen las redirecciones), 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, que incluye 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). Deduplica 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 retroactivamente, 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 incluso si el resultado se produjo 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 activa la deshabilitación automática, descrita más adelante en esta sección, nunca se reintenta) con retroceso exponencial con variación aleatoria (jittered exponential backoff) 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 perdió. Los webhooks no son un registro duradero, así que si necesitas observar cada transición, reconcilia listando u obteniendo el recurso a través de la API.

• Marcas de tiempo: El encabezado webhook-timestamp se marca cuando se firma un intento de entrega y se regenera en cada reintento, por lo que los reintentos no son rechazados por la verificación de antigüedad del SDK. 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. Nunca se siguen las redirecciones; esto deshabilita el endpoint inmediatamente, en el primer intento, con el motivo auto-disabled: endpoint URL returned a redirect (3xx). Si tu endpoint se mueve, actualiza la URL en la Console y vuelve a habilitar el endpoint.
  • La URL del endpoint se resuelve a 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 sostenido, con el motivo auto-disabled after sustained delivery failures. El desencadenante es cuánto tiempo ha estado fallando el endpoint sin interrupción, no un recuento de entregas. Un solo 2xx reinicia la ventana, por lo que un único evento inestable no puede deshabilitar el endpoint.

  Los tres 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 reproducen.