Webhooks abonnieren

Sessions sind lang laufende 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 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 Endpunkt registrieren

Gehe zu Manage > Webhooks in der Console.

Ein Webhook-Endpunkt 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 Endpunkt empfängt. Ein Endpunkt empfängt nur Events, die er abonniert hat, plus Test-Events (siehe Zustellverhalten).
• Signing-Secret: Ein 32-Byte-Secret mit whsec_-Präfix, das bei der Erstellung generiert wird. Es wird nur einmal angezeigt, also speichere es sicher ab, um Webhook-Zustellungen zu verifizieren.

Die Signatur verifizieren

Jede Zustellung enthält einen X-Webhook-Signature-Header. 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 ist oder der Payload älter als fünf Minuten ist.

Setze ANTHROPIC_WEBHOOK_SIGNING_KEY auf das whsec_-präfixierte Secret, das bei der Endpunkt-Erstellung 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)
    # behandle andere Event-Typen

    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 den Empfang zu bestätigen. Alles andere (einschließlich 3xx) zählt als Fehler und löst einen Wiederholungsversuch aus.

Jeder Event-Payload hat dieselbe Struktur, einschließlich des Event-Typs, des Identifiers und des Zeitstempels, wann das Objekt erstellt wurde.

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

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

Zustellverhalten

• Reihenfolge ist nicht garantiert. session.status_idled kann vor session.outcome_evaluation_ended eintreffen, auch wenn das Outcome zuerst erzeugt wurde. Verwende den created_at-Zeitstempel zum Sortieren, falls die Reihenfolge wichtig ist.
• Wiederholungsversuche: Anthropic versucht die Zustellung mindestens einmal erneut. Der Wiederholungsversuch liefert dieselbe event.id.
• Redirects werden nicht verfolgt. Ein 3xx wird als Fehler behandelt. Wenn dein Endpunkt umzieht, aktualisiere die URL in der Console.
• Automatische Deaktivierung: Ein Endpunkt wird automatisch auf disabled gesetzt, mit einem maschinenlesbaren disabled_reason, nach etwa 20 aufeinanderfolgenden fehlgeschlagenen Zustellungen, oder sofort, wenn der Hostname zu einer privaten IP auflöst oder der Endpunkt einen Redirect zurückgibt. Aktiviere ihn manuell in der Console wieder, nachdem du das Problem behoben hast.