Assinar webhooks

Sessões são interações de longa duração. Embora a maioria das interações em tempo real aconteça por meio do fluxo de eventos SSE, os webhooks notificam você sobre mudanças importantes de estado.

Eventos de webhook retornam o type e o id do evento, não o objeto completo. Quando você recebe um evento de webhook, precisa buscar o objeto diretamente com uma chamada GET. Isso evita entregar dados desatualizados em novas tentativas e mantém cada entrega pequena.

Tipos de eventos suportados

Registrar um endpoint

Acesse Manage > Webhooks no Console.

Um endpoint de webhook consiste em:

• URL: Deve ser HTTPS na porta 443 com um hostname resolvível publicamente.
• Tipos de eventos: A lista de valores data.type que este endpoint recebe. Um endpoint recebe apenas eventos aos quais está inscrito, além de eventos de teste (consulte Comportamento de entrega).
• Segredo de assinatura: Um segredo de 32 bytes com prefixo whsec_ gerado na criação. Ele é exibido apenas uma vez, então armazene-o com segurança para verificar as entregas de webhook.

Verificar a assinatura

Cada entrega carrega um cabeçalho X-Webhook-Signature. Use o helper unwrap() do SDK para verificar a assinatura e analisar o evento em uma única etapa. Ele lança uma exceção se a assinatura for inválida ou se o payload tiver mais de cinco minutos.

Defina ANTHROPIC_WEBHOOK_SIGNING_KEY com o segredo prefixado por whsec_ exibido na criação do 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() lança uma exceção se a assinatura for inválida ou o payload estiver 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)
    # trate outros tipos de eventos

    return "", 200

Tratar um evento

Analise o corpo, faça um switch em data.type e busque o recurso pelo ID. Retorne qualquer 2xx para confirmar o recebimento. Qualquer outra coisa (incluindo 3xx) conta como falha e aciona uma nova tentativa.

Todo payload de evento tem a mesma estrutura, incluindo o tipo de evento, o identificador e o timestamp de quando o objeto foi criado.

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

O event.id de nível superior é único por evento, não por entrega. Se você receber o mesmo event.id duas vezes, trata-se de uma nova tentativa e você pode descartá-lo.

Comportamento de entrega

• A ordem não é garantida. session.status_idled pode chegar antes de session.outcome_evaluation_ended, mesmo que o resultado tenha sido produzido primeiro. Use o timestamp created_at para ordenar, se a ordem for importante.
• Novas tentativas: A Anthropic tenta novamente pelo menos uma vez. A nova tentativa entrega o mesmo event.id.
• Redirecionamentos não são seguidos. Um 3xx é tratado como falha. Se o seu endpoint mudar, atualize a URL no Console.
• Desativação automática: Um endpoint é automaticamente definido como disabled com um disabled_reason legível por máquina após aproximadamente 20 entregas consecutivas com falha, ou imediatamente se o hostname resolver para um IP privado ou se o endpoint retornar um redirecionamento. Reative manualmente no Console após resolver o problema.