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 de estado importantes.

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

Tipos de eventos suportados

Registrar um endpoint

Acesse Manage > Webhooks no Claude 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 só recebe eventos nos quais está inscrito.
• Segredo de assinatura: Um segredo de 32 bytes com prefixo whsec_ gerado na criação. Ele é exibido apenas uma vez, portanto armazene-o com segurança para verificar as entregas de webhook.

Verificar a assinatura

Toda entrega carrega os cabeçalhos webhook-id, webhook-timestamp e webhook-signature. Use o helper unwrap() do SDK para verificar a assinatura e fazer o parse do evento em uma única etapa. Ele lança uma exceção se a assinatura for inválida ou se o payload tiver mais de 5 minutos.

Defina ANTHROPIC_WEBHOOK_SIGNING_KEY com o segredo de prefixo 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 desatualizado
        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)
    # tratar outros tipos de evento

    return "", 200

Tratar um evento

Faça o parse do corpo, faça um switch em data.type e busque o recurso pelo ID. Retorne qualquer 2xx para confirmar o recebimento. Qualquer outra resposta conta contra o endpoint: um 3xx o desativa imediatamente (redirecionamentos nunca são seguidos), enquanto outras falhas são tentadas novamente; consulte Comportamento de entrega para as regras de novas tentativas e desativação automática.

Todo payload de evento tem a mesma estrutura, incluindo o tipo do evento, o identificador e o timestamp de quando o evento ocorreu.

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

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

• Duplicatas: Um endpoint pode receber o mesmo evento mais de uma vez, e toda tentativa entrega o mesmo event.id de nível superior (o mesmo valor do cabeçalho webhook-id). Faça a deduplicação com base nele.

• Escopo da assinatura: Um evento é entregue apenas aos endpoints inscritos em seu tipo no momento em que é emitido. Um evento emitido enquanto nenhum endpoint está inscrito em seu tipo nunca é entregue, e inscrever-se depois não o preenche retroativamente, portanto inscreva-se em um tipo de evento antes de precisar dele.

• A ordenação não é garantida. Os eventos não são entregues na ordem em que ocorreram: session.status_idled pode chegar antes de session.outcome_evaluation_ended mesmo que o resultado tenha sido produzido primeiro, e um evento .deleted pode chegar antes do evento .archived do mesmo recurso. Conduza seu estado a partir do recurso que você busca, não da ordem em que os eventos chegam.

• Novas tentativas: Para cada endpoint e evento, a Anthropic faz até três tentativas de entrega (uma resposta que dispara a desativação automática, descrita mais adiante nesta seção, nunca é tentada novamente) com backoff exponencial com jitter entre 5 e 120 segundos. Toda tentativa entrega o mesmo event.id. Após a falha da última tentativa, o evento é descartado: ele não é enfileirado para entrega posterior e não há sinal de que foi perdido. Webhooks não são um log durável, portanto, se você precisa observar cada transição, faça a reconciliação listando ou buscando o recurso por meio da API.

• Timestamps: O cabeçalho webhook-timestamp é carimbado quando uma tentativa de entrega é assinada e é regenerado a cada nova tentativa, de modo que as novas tentativas não são rejeitadas pela verificação de atualidade do SDK. Ele é o relógio da tentativa de entrega, não do evento: use o created_at do payload do evento para saber quando o evento ocorreu.

• Desativação automática: Um endpoint é automaticamente definido como disabled com um disabled_reason legível por máquina em três casos:

  • O endpoint retorna uma resposta 3xx. Redirecionamentos nunca são seguidos; isso desativa o endpoint imediatamente, na primeira tentativa, com o motivo auto-disabled: endpoint URL returned a redirect (3xx). Se o seu endpoint mudar de lugar, atualize a URL no Console e reative o endpoint.
  • A URL do endpoint resolve para um endereço IP não público quando a Anthropic se conecta. Isso desativa o endpoint imediatamente, com o motivo auto-disabled: endpoint URL resolved to an invalid address.
  • As entregas ao endpoint falham continuamente por um período prolongado, com o motivo auto-disabled after sustained delivery failures. O gatilho é por quanto tempo o endpoint está falhando sem interrupção, não uma contagem de entregas. Um único 2xx reinicia a janela, portanto um único evento instável não consegue desativar o endpoint.

  Todos os três são reversíveis: reative o endpoint no Console depois de resolver o problema. Eventos emitidos enquanto o endpoint estava desativado não são reproduzidos novamente.