Iscriviti 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 durante i tentativi ripetuti e mantiene ogni consegna di piccole dimensioni.

Tipi di evento supportati

Registra un endpoint

Nella Claude Console, vai alla pagina Webhooks (platform.claude.com/settings/workspaces/default/webhooks). Ogni endpoint appartiene a un workspace. Seleziona il workspace desiderato nel selettore dei workspace nella barra laterale.

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.
• Segreto di firma: Un segreto di 32 byte con prefisso whsec_ generato al momento della creazione. Viene mostrato una sola volta, quindi conservalo in modo sicuro per verificare le consegne dei webhook.

Verifica la firma

Ogni consegna include gli header webhook-id, webhook-timestamp e 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 5 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 è scaduto
        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 gli altri tipi di evento

    return "", 200

Gestisci un evento

Analizza il corpo, esegui uno switch su data.type e recupera la risorsa tramite ID. Restituisci un qualsiasi 2xx per confermare la ricezione. Qualsiasi altra risposta viene conteggiata a sfavore dell'endpoint: un 3xx lo disabilita immediatamente (i reindirizzamenti non vengono mai seguiti), mentre gli altri errori vengono ritentati; consulta Comportamento di consegna per le regole sui tentativi ripetuti e sulla disabilitazione automatica.

Ogni payload di evento ha la stessa struttura, che include il tipo di evento, l'identificatore e il timestamp del momento in cui l'evento si è verificato.

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

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

Comportamento di consegna

• Duplicati: Un endpoint può ricevere lo stesso evento più di una volta, e ogni tentativo consegna lo stesso event.id di primo livello (lo stesso valore dell'header webhook-id). Esegui la deduplicazione su di esso.

• Ambito dell'iscrizione: Un evento viene consegnato solo agli endpoint iscritti al suo tipo nel momento in cui viene emesso. Un evento emesso mentre nessun endpoint è iscritto al suo tipo non viene mai consegnato, e iscriversi in seguito non lo recupera retroattivamente, quindi iscriviti a un tipo di evento prima di averne bisogno.

• L'ordine non è garantito. Gli eventi non vengono consegnati nell'ordine in cui si sono verificati: session.status_idled potrebbe arrivare prima di session.outcome_evaluation_ended anche se il risultato è stato prodotto per primo, e un evento .deleted può arrivare prima dell'evento .archived per la stessa risorsa. Basa il tuo stato sulla risorsa che recuperi, non sull'ordine di arrivo degli eventi.

• Tentativi ripetuti: Per ogni endpoint ed evento, Anthropic effettua fino a tre tentativi di consegna (una risposta che attiva la disabilitazione automatica, descritta più avanti in questa sezione, non viene mai ritentata) con backoff esponenziale con jitter tra 5 e 120 secondi. Ogni tentativo consegna lo stesso event.id. Dopo il fallimento dell'ultimo tentativo, l'evento viene scartato: non viene messo in coda per una consegna successiva e non c'è alcun segnale che sia andato perso. I webhook non sono un log durevole, quindi se hai bisogno di osservare ogni transizione, esegui una riconciliazione elencando o recuperando la risorsa tramite l'API.

• Timestamp: L'header webhook-timestamp viene impostato quando un tentativo di consegna viene firmato e viene rigenerato a ogni tentativo ripetuto, quindi i tentativi ripetuti non vengono rifiutati dal controllo di freschezza dell'SDK. È l'orologio del tentativo di consegna, non dell'evento: usa il created_at del payload dell'evento per sapere quando l'evento si è verificato.

• Disabilitazione automatica: Un endpoint viene impostato automaticamente su disabled con un disabled_reason leggibile dalla macchina in tre casi:

  • L'endpoint restituisce una risposta 3xx. I reindirizzamenti non vengono mai seguiti; questo disabilita l'endpoint immediatamente, al primo tentativo, con il motivo auto-disabled: endpoint URL returned a redirect (3xx). Se il tuo endpoint si sposta, aggiorna l'URL nella Console e riabilita l'endpoint.
  • L'URL dell'endpoint si risolve in un indirizzo IP non pubblico quando Anthropic si connette. Questo disabilita l'endpoint immediatamente, con il motivo auto-disabled: endpoint URL resolved to an invalid address.
  • Le consegne all'endpoint falliscono continuamente per un periodo prolungato, con il motivo auto-disabled after sustained delivery failures. L'attivazione dipende da quanto tempo l'endpoint ha continuato a fallire senza interruzioni, non da un numero di consegne. Un singolo 2xx azzera la finestra, quindi un singolo evento instabile non può disabilitare l'endpoint.

  Tutti e tre i casi sono reversibili: riabilita l'endpoint nella Console dopo aver risolto il problema. Gli eventi emessi mentre l'endpoint era disabilitato non vengono riprodotti.