Iscriviti ai webhook

Le sessioni sono interazioni di lunga durata. Mentre la maggior parte delle interazioni in tempo reale avviene attraverso 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 eventi supportati

Registra un endpoint

Visita Manage > Webhooks nella Claude Console.

Un endpoint webhook è composto da:

• URL: Deve essere HTTPS sulla porta 443 con un hostname risolvibile pubblicamente.
• Tipi di eventi: 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 alla creazione. Viene mostrato solo una volta, quindi conservalo in modo sicuro per verificare le consegne dei webhook.

Verifica la firma

Ogni consegna porta 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 è 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

Gestisci un evento

Analizza il body, esegui uno switch su data.type e recupera la risorsa tramite ID. Restituisci qualsiasi 2xx per confermare. Qualsiasi altra risposta conta contro l'endpoint: un 3xx lo disabilita immediatamente (i redirect non vengono mai seguiti), mentre altri fallimenti vengono ritentati; consulta Comportamento di consegna per le regole di ritentativo e disabilitazione automatica.

Ogni payload di evento ha la stessa struttura, incluso il tipo di evento, l'identificatore e il timestamp di quando si è verificato l'evento.

{
  "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, è un ritentativo 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). Deduplica su di esso.

• Ambito di 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, quindi iscriviti a un tipo di evento prima di averne bisogno.

• L'ordinamento 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 l'esito è stato prodotto per primo, e un evento .deleted può arrivare prima dell'evento .archived per la stessa risorsa. Guida il tuo stato dalla risorsa che recuperi, non dall'ordine in cui arrivano gli eventi.

• Ritentativi: 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 che l'ultimo tentativo fallisce, 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, riconcilia elencando o recuperando la risorsa tramite l'API.

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

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

  • L'endpoint restituisce una risposta 3xx. I redirect 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. Il trigger è da quanto tempo l'endpoint sta fallendo senza interruzione, non un conteggio di consegne. Un singolo 2xx reimposta la finestra, quindi un singolo evento instabile non può disabilitare l'endpoint.

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