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 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, debes 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 resoluble 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 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 es inválida o si el payload 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)
    # manejar 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 (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 payload 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 en función de é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 dispara la deshabilitación automática, descrita más adelante en esta sección, nunca se reintenta) con backoff exponencial con jitter 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 estampa 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 frescura del SDK. Es el reloj del intento de entrega, no del evento: usa el created_at del payload 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 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 disparador es cuánto tiempo ha estado fallando el endpoint sin interrupción, no un conteo 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 vuelven a reproducir.