Webhooks abonnieren

Sessions sind langlaufende Interaktionen. Während die meisten Echtzeit-Interaktionen über den SSE-Event-Stream ablaufen, benachrichtigen dich Webhooks über wichtige Zustandsänderungen.

Webhook-Events liefern den Event-type und die id zurück, nicht das vollständige Objekt. Wenn du ein Webhook-Event erhältst, musst du das Objekt direkt mit einem GET-Aufruf abrufen. Das vermeidet die Zustellung veralteter Daten bei Wiederholungsversuchen und hält jede Zustellung klein.



Unterstützte Event-Typen



Einen Endpoint registrieren

Besuche Manage > Webhooks in der Console.

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 eine Exception, wenn die Signatur ungültig oder die Payload älter als fünf 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 die 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 per ID ab. Gib einen beliebigen 2xx-Status zurück, um zu bestätigen. Jede andere Antwort wird dem Endpoint angelastet: Ein 3xx deaktiviert ihn sofort (Redirects werden nie gefolgt), während andere Fehler wiederholt werden; siehe Zustellverhalten für die Regeln zu Wiederholungen und automatischer Deaktivierung.

Jede Event-Payload hat dieselbe Struktur, einschließlich des Event-Typs, des Identifiers und des Zeitstempels, wann das Event aufgetreten 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 erhältst, handelt es sich um einen Wiederholungsversuch und du kannst sie verwerfen.



Zustellverhalten

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

• 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 füllt es nicht nachträglich auf. Abonniere einen Event-Typ also, bevor du ihn brauchst.

• Die Reihenfolge ist nicht garantiert. Events werden nicht in der Reihenfolge zugestellt, in der sie aufgetreten 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 Ressource ab, die du abrufst, 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 die später in diesem Abschnitt beschriebene automatische Deaktivierung auslöst, wird nie wiederholt) mit jittered exponential backoff 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 eine 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 ab, indem du die Ressource über die API auflistest oder abrufst.

• Zeitstempel: Der webhook-timestamp-Header wird gestempelt, wenn ein Zustellversuch signiert wird, und wird bei jedem Wiederholungsversuch neu generiert, sodass Wiederholungen nicht von der Aktualitätsprüfung des SDK abgelehnt werden. Er ist die Uhr für den Zustellversuch, nicht für das Event: Verwende das created_at der Event-Payload dafür, wann das Event aufgetreten 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. Redirects werden nie gefolgt; 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 löst zu einer nicht öffentlichen IP-Adresse auf, wenn Anthropic sich verbindet. Dies deaktiviert den Endpoint sofort, mit dem Grund auto-disabled: endpoint URL resolved to an invalid address.
  • Zustellungen an den Endpoint schlagen über einen anhaltenden Zeitraum kontinuierlich 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 einzelner 2xx setzt das Zeitfenster zurück, sodass ein einzelnes instabiles Event den Endpoint nicht deaktivieren kann.

  Alle drei 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 abgespielt.