Webhooks abonnieren

Sessions sind lang laufende Interaktionen. Während die meisten Echtzeit-Interaktionen über den SSE-Event-Stream stattfinden, benachrichtigen dich „webhooks" (Webhooks) über wichtige Zustandsänderungen.

Webhook-Events geben den Event-type und die id zurück, nicht das vollständige Objekt. Wenn du ein Webhook-Event empfängst, musst du das Objekt direkt mit einem GET-Aufruf abrufen. Dadurch wird vermieden, dass bei Wiederholungsversuchen veraltete Daten zugestellt werden, und jede Zustellung bleibt klein.

Unterstützte Event-Typen

Einen Endpoint registrieren

Gehe in der Claude Console zur Seite Webhooks (platform.claude.com/settings/workspaces/default/webhooks). Jeder Endpoint gehört zu einem Workspace. Wähle den gewünschten Workspace in der Workspace-Auswahl in der Seitenleiste aus.

Ein Webhook-Endpoint besteht aus:

• URL: Muss HTTPS auf Port 443 mit einem öffentlich auflösbaren Hostnamen sein.
• Event-Typen: Die Liste der data.type-Werte, die dieser Endpoint empfängt. Ein Endpoint empfängt nur Events, die er abonniert hat.
• Signing Secret: Ein 32-Byte-Secret mit dem Präfix whsec_, das bei der Erstellung generiert wird. Es wird nur einmal angezeigt, speichere es also sicher, um Webhook-Zustellungen zu verifizieren.

Die Signatur verifizieren

Jede Zustellung enthält die Header webhook-id, webhook-timestamp und webhook-signature. Verwende den unwrap()-Helper des SDK, um die Signatur zu verifizieren und das Event in einem Schritt zu parsen. Er wirft einen Fehler, wenn die Signatur ungültig ist oder der Payload älter als 5 Minuten ist.

Setze ANTHROPIC_WEBHOOK_SIGNING_KEY auf das Secret mit dem Präfix whsec_, das bei der Erstellung des Endpoints angezeigt wurde.

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() löst eine Exception aus, wenn die Signatur ungültig oder der Payload veraltet ist
        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)
    # andere Event-Typen behandeln

    return "", 200

Ein Event verarbeiten

Parse den Body, verzweige anhand von data.type und rufe die Ressource über ihre ID ab. Gib einen beliebigen 2xx-Status zurück, um den Empfang zu bestätigen. Jede andere Antwort wird dem Endpoint angerechnet: Ein 3xx deaktiviert ihn sofort (Weiterleitungen werden nie verfolgt), während andere Fehler erneut versucht werden; siehe Zustellverhalten für die Regeln zu Wiederholungsversuchen und automatischer Deaktivierung.

Jeder Event-Payload hat dieselbe Struktur, einschließlich des Event-Typs, der Kennung und des Zeitstempels, zu dem das Event eingetreten ist.

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

Die event.id auf oberster Ebene ist pro Event eindeutig, nicht pro Zustellung. Wenn du dieselbe event.id zweimal empfängst, handelt es sich um einen Wiederholungsversuch, und du kannst ihn verwerfen.

Zustellverhalten

• Duplikate: Ein Endpoint kann dasselbe Event mehr als einmal empfangen, und jeder Versuch liefert dieselbe event.id auf oberster Ebene (denselben Wert wie der webhook-id-Header). Dedupliziere anhand dieser ID.

• Abonnement-Umfang: Ein Event wird nur an Endpoints zugestellt, die seinen Typ zum Zeitpunkt der Ausgabe abonniert haben. Ein Event, das ausgegeben wird, während kein Endpoint seinen Typ abonniert hat, wird nie zugestellt, und ein späteres Abonnement liefert es nicht nachträglich aus. Abonniere einen Event-Typ also, bevor du ihn benötigst.

• Die Reihenfolge ist nicht garantiert. Events werden nicht in der Reihenfolge zugestellt, in der sie eingetreten sind: session.status_idled kann vor session.outcome_evaluation_ended eintreffen, selbst wenn das Outcome zuerst erzeugt wurde, und ein .deleted-Event kann vor dem .archived-Event für dieselbe Ressource eintreffen. Leite deinen Zustand aus der abgerufenen Ressource ab, nicht aus der Reihenfolge, in der Events eintreffen.

• Wiederholungsversuche: Für jeden Endpoint und jedes Event unternimmt Anthropic bis zu drei Zustellversuche (eine Antwort, die eine automatische Deaktivierung auslöst, wie weiter unten in diesem Abschnitt beschrieben, wird nie erneut versucht) mit exponentiellem Backoff mit Jitter zwischen 5 und 120 Sekunden. Jeder Versuch liefert dieselbe event.id. Nachdem der letzte Versuch fehlgeschlagen ist, wird das Event verworfen: Es wird nicht für eine spätere Zustellung in die Warteschlange gestellt, und es gibt kein Signal, dass es verloren gegangen ist. Webhooks sind kein dauerhaftes Log. Wenn du also jeden Übergang beobachten musst, gleiche den Zustand ab, indem du die Ressource über die API auflistest oder abrufst.

• Zeitstempel: Der webhook-timestamp-Header wird gesetzt, wenn ein Zustellversuch signiert wird, und bei jedem Wiederholungsversuch neu generiert, sodass Wiederholungsversuche nicht von der Aktualitätsprüfung des SDK abgelehnt werden. Er ist die Uhr für den Zustellversuch, nicht für das Event: Verwende created_at aus dem Event-Payload für den Zeitpunkt, zu dem das Event eingetreten ist.

• Automatische Deaktivierung: Ein Endpoint wird in drei Fällen automatisch auf disabled gesetzt, mit einem maschinenlesbaren disabled_reason:

  • Der Endpoint gibt eine 3xx-Antwort zurück. Weiterleitungen werden nie verfolgt; dies deaktiviert den Endpoint sofort, beim ersten Versuch, mit dem Grund auto-disabled: endpoint URL returned a redirect (3xx). Wenn dein Endpoint umzieht, aktualisiere die URL in der Console und aktiviere den Endpoint erneut.
  • Die URL des Endpoints wird beim Verbindungsaufbau durch Anthropic zu einer nicht öffentlichen IP-Adresse aufgelöst. Dies deaktiviert den Endpoint sofort, mit dem Grund auto-disabled: endpoint URL resolved to an invalid address.
  • Zustellungen an den Endpoint schlagen über einen längeren Zeitraum ununterbrochen fehl, mit dem Grund auto-disabled after sustained delivery failures. Der Auslöser ist, wie lange der Endpoint ohne Unterbrechung fehlschlägt, nicht eine Anzahl von Zustellungen. Ein einzelnes 2xx setzt das Zeitfenster zurück, sodass ein einzelnes unzuverlässiges Event den Endpoint nicht deaktivieren kann.

  Alle drei Fälle sind umkehrbar: Aktiviere den Endpoint in der Console erneut, nachdem du das Problem behoben hast. Events, die ausgegeben wurden, während der Endpoint deaktiviert war, werden nicht erneut zugestellt.