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, 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 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 de data.type que recibe este endpoint. Un endpoint solo recibe los eventos a los que está suscrito, además de los eventos de prueba (consulta Comportamiento de entrega).
• 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 webhooks.

Verificar la firma

Cada entrega incluye un encabezado X-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 cinco 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 cosa (incluido 3xx) cuenta como un fallo y desencadena un reintento.

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 se creó el objeto.

{
  "type": "event",
  "id": "event_01ABC...",
  "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, se trata de un reintento y puedes descartarlo.

Comportamiento de entrega

• El orden no está garantizado. session.status_idled puede llegar antes que session.outcome_evaluation_ended incluso si el resultado se produjo primero. Usa la marca de tiempo created_at para ordenar si el orden es importante.
• Reintentos: Anthropic reintenta al menos una vez. El reintento entrega el mismo event.id.
• No se siguen las redirecciones. Un 3xx se trata como un fallo. Si tu endpoint cambia de ubicación, actualiza la URL en Console.
• Desactivación automática: Un endpoint se establece automáticamente en disabled con un disabled_reason legible por máquina después de aproximadamente 20 entregas fallidas consecutivas, o inmediatamente si el nombre de host se resuelve a una IP privada o el endpoint devuelve una redirección. Vuelve a habilitarlo manualmente en Console después de resolver el problema.