Iscriversi ai webhook

Le sessioni sono interazioni di lunga durata. Mentre la maggior parte delle interazioni in tempo reale avviene tramite lo stream di eventi SSE, i webhook ti notificano i principali cambiamenti di stato.

Gli eventi webhook restituiscono il type e l'id dell'evento, non l'oggetto completo. Quando ricevi un evento webhook, devi recuperare l'oggetto direttamente con una chiamata GET. Questo evita di consegnare dati obsoleti nei tentativi ripetuti e mantiene ogni consegna di dimensioni ridotte.

Tipi di eventi supportati

Registrare un endpoint

Visita Manage > Webhooks nella Console.

Un endpoint webhook è composto da:

• URL: Deve essere HTTPS sulla porta 443 con un hostname risolvibile pubblicamente.
• Tipi di evento: L'elenco dei valori data.type che questo endpoint riceve. Un endpoint riceve solo gli eventi a cui è iscritto, più gli eventi di test (vedi Comportamento di consegna).
• Segreto di firma: Un segreto di 32 byte con prefisso whsec_ generato alla creazione. Viene mostrato una sola volta, quindi conservalo in modo sicuro per verificare le consegne dei webhook.

Verificare la firma

Ogni consegna include un header X-Webhook-Signature. Usa l'helper unwrap() dell'SDK per verificare la firma e analizzare l'evento in un unico passaggio. Genera un'eccezione se la firma non è valida o se il payload ha più di cinque minuti.

Imposta ANTHROPIC_WEBHOOK_SIGNING_KEY sul segreto con prefisso whsec_ mostrato alla creazione dell'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() solleva un'eccezione se la firma non è valida o il payload è 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)
    # gestisci altri tipi di evento

    return "", 200

Gestire un evento

Analizza il body, esegui uno switch su data.type e recupera la risorsa tramite ID. Restituisci qualsiasi 2xx per confermare la ricezione. Qualsiasi altra risposta (incluso 3xx) viene considerata un fallimento e attiva un nuovo tentativo.

Ogni payload di evento ha la stessa struttura, che include il tipo di evento, l'identificatore e il timestamp di quando l'oggetto è stato creato.

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

L'event.id di primo livello è univoco per evento, non per consegna. Se ricevi lo stesso event.id due volte, si tratta di un nuovo tentativo e puoi scartarlo.

Comportamento di consegna

• L'ordinamento non è garantito. session.status_idled potrebbe arrivare prima di session.outcome_evaluation_ended anche se l'outcome è stato prodotto per primo. Usa il timestamp created_at per ordinare se l'ordinamento è importante.
• Nuovi tentativi: Anthropic riprova almeno una volta. Il nuovo tentativo consegna lo stesso event.id.
• I redirect non vengono seguiti. Un 3xx viene trattato come un fallimento. Se il tuo endpoint viene spostato, aggiorna l'URL nella Console.
• Disabilitazione automatica: Un endpoint viene automaticamente impostato su disabled con un disabled_reason leggibile dalla macchina dopo circa 20 consegne fallite consecutive, oppure immediatamente se l'hostname si risolve in un IP privato o l'endpoint restituisce un redirect. Riabilitalo manualmente nella Console dopo aver risolto il problema.