Inference Hooks einrichten: Endpunkt anbinden, Verdict zurückgeben, Rollout steuern

Kurz gesagt: Inference Hooks einzurichten sind zwei Arbeiten. Ein Owner schaltet die Funktion in claude.ai unter Organization settings › Data and privacy frei, trägt eine HTTPS-Adresse ein und stellt Timeout, Failure Handling und Rollout ein. Parallel baut jemand den AI Security Server, der auf jeden signierten POST mit {"action": "allow"} oder {"action": "deny"} antwortet. HTTP 200, sonst zählt es als Fehler und nicht als Ablehnung.

Was du vorher brauchst

Voraussetzung	Stand
Plan	Claude Enterprise. Platform-Organisationen, also API-Zugriff über die Claude Platform, sind nicht abgedeckt. Auf Amazon Bedrock und Google Cloud gibt es die Funktion nicht.
Rolle	Die Berechtigung `organization:manage`, die nur Owner und Primary Owner haben. Die Rolle Admin reicht nicht.
Endpunkt	Eine `https://`-Adresse auf Port 443, auf einem öffentlich erreichbaren Host, ohne Weiterleitung, mit einem Zertifikat aus dem öffentlichen CA-Speicher.
Reifegrad	Beta. Feldnamen, Request-Formate und Header können sich laut Doku noch ändern.

Private Adressen, Loopback und Carrier-Grade-NAT lehnt Anthropic schon beim Verbindungsaufbau ab. Reverse-Tunnel wie ngrok sind gesperrt, die Netzwerkregeln blocken sie. Teste also nicht durch einen Tunnel, sondern hoste auf einer Domain, die dir gehört.

Die drei Zustände

Es hilft, die Einstellungen als drei Zustände zu lesen statt als Sammlung von Schaltern:

Zustand	Was eingestellt ist	Was passiert
Aus	Enforce verdicts aus	Dein Server wird nie kontaktiert, keine Prüfung
Shadow	Enforce verdicts an, Mode auf Shadow mode	Dein Server bekommt Prompts und antwortet, blockiert wird nichts
Scharf	Enforce verdicts an, Mode auf Allow the request oder Block the request	Ein Deny blockiert die Anfrage

Einrichten, Schritt für Schritt

1. Funktion freischalten

claude.ai › Organization settings › Data and privacy › Abschnitt Inference hooks › Allow for your organization einschalten.

Das schaltet nur die Einstellungsseite frei. Enforce verdicts wird dabei immer zwangsweise auf aus gesetzt, auch wenn eine frühere Konfiguration schon scharf war. Freischalten allein startet also nie eine Prüfung.

2. Einstellungsseite öffnen

Die Seite hängt unter Data and privacy, sie hat keinen eigenen Eintrag in der Navigation; der Brotkrumenpfad liest sich als Data and privacy / Inference hooks. Solange kein Endpunkt gespeichert ist, warnt die Seite, dass noch nichts geprüft wird, und Enforce verdicts trägt das Abzeichen Requires endpoint.

3. Endpunkt eintragen

Configure öffnet den Dialog Set up endpoint. Dort kommt die Endpoint URL rein, und nur https:// wird akzeptiert. Mehr fragt der Dialog an dieser Stelle nicht. Next speichert; danach heißt der Knopf Edit.

Die ganze eingetragene Adresse ist der Endpunkt. Es gibt keinen festen Pfad-Anhang, du kannst also jeden Pfad wählen, der zu deinem Server passt.

4. Signing Secret wegschließen

Beim ersten Speichern erzeugt Claude das Webhook Signing Secret und zeigt es genau einmal. Kopier es und leg es sicher ab, bevor du auf Next klickst. Abrufen lässt es sich später nicht mehr, nur rotieren.

5. Header setzen und Verbindung testen

Next auf dem Secret-Dialog öffnet den Endpunkt-Dialog erneut, jetzt mit zwei weiteren Feldern.

Custom request headers: bis zu 16 feste Header, die bei jeder Anfrage mitgehen, damit dein Server den Aufrufer authentifizieren kann. Die Werte liegen verschlüsselt und werden nie wieder angezeigt; sichtbar bleiben nur die Namen. Weil sie nur schreibbar sind, musst du bei jeder Änderung alle Werte neu eintippen. Änderst du die URL, löscht Claude alle gespeicherten Werte, damit deine Zugangsdaten nicht an ein neues Ziel gehen. Danach also neu eintragen.

Für die Namen gelten die üblichen HTTP-Token-Zeichen mit - statt _. Reserviert und damit gesperrt sind Framing-Header wie Content-* und Host, Proxy- und Cookie-Header, Client-Adress-Header wie X-Forwarded-*, die webhook-*-Signaturheader und alles mit dem Präfix X-Anthropic-. Werte müssen druckbares ASCII sein.

Test connection schickt einen synthetischen Test-Prompt an die URL und die Header, die gerade im Formular stehen, nicht an die gespeicherten. Gespeicherte Header-Werte also vor dem Test neu eintragen. Das Ergebnis nennt, ob dein Server mit allow oder deny geantwortet hat; ein Server, der vorsichtshalber alles ablehnt, fällt damit auf, bevor du scharf schaltest.

Fehlermeldung	Woran es liegt
URL rejected	Die Adresse hat die Formprüfung nicht bestanden. `https://` auf Port 443.
Private or internal IP	Der Host löst auf eine private oder interne Adresse auf.
Timeout	Kein Verdict innerhalb des Zeitbudgets.
Transport error	DNS, TLS-Handshake oder Verbindung gescheitert.
Non-200 status	Etwas anderes als HTTP 200. Weiterleitungen werden nicht verfolgt und zählen als Fehler.
Unparseable response	Antwort da, aber kein gültiges Verdict.
Signing secret required	Kein Secret vorhanden, der Test wäre unsigniert. Unter Request signing Generate secret klicken.

6. Failure Handling und Timeout

Unter Failure handling legt Mode fest, was gilt, solange dein Server nicht erreichbar ist oder zu langsam antwortet:

Block the request: Inferenz stoppt, wenn kein Verdict kommt (fail closed).
Allow the request: die Anfrage geht ungeprüft ans Modell (fail open).

Die dritte Option im selben Dropdown, Shadow mode, ist kein Ausfallverhalten, sondern ein Rollout-Werkzeug.

Prompt verdict timeout (ms) steht zwischen 1 und 10.000, voreingestellt sind 5.000. Das Budget deckt den kompletten Austausch ab, also Verbindung, TLS-Handshake, Anfrage und Antwort. Ein zu langsames Verdict zählt wie ein nicht erreichbarer Server. Nimm den niedrigsten Wert, den dein Server zuverlässig hält.

Änderungen in diesem Abschnitt speichern sich beim Eintippen. Beim ersten Speichern stehen Allow the request und 5.000 ms.

7. Rollout-Anteil

Unter Rollout bestimmt Requests inspected (%) zwischen 0 und 100, welcher Anteil geprüft wird. Gewürfelt wird einmal je Gesprächsrunde, eine Unterhaltung kann über ihre Runden hinweg also teils geprüft und teils ungeprüft sein. Was außerhalb der Stichprobe liegt, läuft ungeprüft durch, auch bei Failure Handling auf Block the request.

8. Scharf schalten

Enforce verdicts einschalten und im Dialog bestätigen, der dir deine Failure-Handling-Wahl noch einmal vorhält. Rechne mit etwa einer Minute, bis die Änderung alle Server von Anthropic erreicht hat; laufende Anfragen beenden sich nach der alten Einstellung. Ausschalten wirkt genauso schnell und behält die Konfiguration.

Wer erst zusehen will: vorher in Schritt 6 Mode auf Shadow mode stellen, dann Enforce verdicts einschalten. Dein Server bekommt echte Prompts und antwortet wie im Ernstfall, blockiert wird nichts, auch ein Deny nicht, auch ein Ausfall nicht, und der Nutzer merkt nichts. Auf der Einstellungsseite steht dann das Abzeichen Shadow mode — not blocking. Zurück geht es, indem du Mode wieder auf Allow the request oder Block the request stellst.

Der Server: das kleinste, was funktioniert

Der kleinste brauchbare Server liest die Anfrage und lässt sie durch. Dieses Beispiel steht so in der Doku:

# Start mit: python server.py
from http.server import BaseHTTPRequestHandler, ThreadingHTTPServer


class VerdictHandler(BaseHTTPRequestHandler):
    protocol_version = "HTTP/1.1"  # Verbindung zwischen Verdicts offen halten

    def do_POST(self):
        # Body leeren; Transkripte können megabytegroß sein.
        self.rfile.read(int(self.headers.get("Content-Length", 0)))
        verdict = b'{"action": "allow"}'
        self.send_response(200)
        self.send_header("Content-Type", "application/json")
        self.send_header("Content-Length", str(len(verdict)))
        self.end_headers()
        self.wfile.write(verdict)


ThreadingHTTPServer(("", 8000), VerdictHandler).serve_forever()

Der nimmt alles an, auch unsignierte Anfragen. Die Signaturprüfung kommt dazu, bevor du scharf schaltest.

Was ankommt

Jede Anfrage trägt diese festen Header, dazu deine eigenen und die webhook-*-Signaturheader:

Header	Wert
`Content-Type`	`application/json`
`User-Agent`	`anthropic-dlp/1`
`Accept-Encoding`	`identity`

Der Body ist ein JSON-Objekt. Heute gibt es genau ein Ereignis, den Prompt-Frame, einmal je geprüfter Inferenz-Anfrage und vor der Inferenz:

{
  "type": "prompt",
  "request_id": "req_abc123",
  "tenant_id": "11111111-1111-1111-1111-111111111111",
  "actor": {
    "type": "user",
    "id": "user_01AbCdEfGhIjKlMnOpQrStUv",
    "email_address": "alice@example.com"
  },
  "source": { "application": "claude-ai" },
  "session_id": "22222222-2222-2222-2222-222222222222",
  "model": "claude-sonnet-4-5",
  "messages": [],
  "metadata": {}
}

request_id ist derselbe Wert wie der Header webhook-id. source.application ist ein offener String, keine geschlossene Liste: gängig sind claude-ai, claude-code und cowork, Verbindungstests und die Wiederbelebungsprüfungen des Circuit Breakers kommen als config-test. Behandle das Feld als Wegweiser, nicht als Vertrauensgrenze.

In messages steht das Transkript, wie der Nutzer es sieht: Text, Tool-Aufrufe und deren Ergebnisse, extrahierter Text aus Anhängen, frühere Runden. Vier Blocktypen gibt es: text, tool_use, tool_result und attachment. Nicht enthalten sind System-Prompts, Tool-Definitionen, interner Kontext von Anthropic, Claudes verborgene Überlegungen und rohe Dateibytes.

Zwei Dinge, die in der Praxis stolpern lassen:

Eine Runde, deren Blöcke alle wegfallen, fehlt komplett. Verlass dich nicht darauf, dass sich user und assistant sauber abwechseln.
Transkripte kommen ungekürzt. In der Praxis hält das Kontextfenster die Bodys unter etwa 10 MB, das Protokoll erlaubt 64 MiB. Verbreitete Voreinstellungen liegen weit darunter: client_max_body_size bei nginx steht auf 1 MB, express.json() auf 100 kB. Ein abgewiesener Body ist ein Webhook-Fehler, und bei Failure Handling auf Allow the request geht der überlange Prompt dann ungeprüft ans Modell.

Was zurückgeht

HTTP 200 und ein JSON-Verdict, für beide Ausgänge. Durchlassen:

{ "action": "allow" }

Ablehnen:

{
  "action": "deny",
  "deny_reason": "This prompt appears to contain customer payment card data, which your organization's policy does not allow.",
  "reference_id": "scan_01HXPT4R9V"
}

Feld	Grenzen	Bedeutung
`action`	`allow` oder `deny`, Pflicht	Jeder andere Wert ist ein Webhook-Fehler, keine Ablehnung.
`deny_reason`	String oder null, höchstens 500 Zeichen	Was der Nutzer sieht. Längeres wird gekürzt. Bei allow ignoriert.
`reference_id`	String oder null, höchstens 50 Zeichen aus `[A-Za-z0-9._:/-]`	Deine eigene Kennung für diese Bewertung. Landet in der Aktivität `inference_hooks_request_denied` und wird dem Nutzer nie gezeigt. Keine Inhalte, keine personenbezogenen Daten.

Ein Deny geht nie an einem Formfehler verloren: Ein zu langer deny_reason wird gekürzt, ein ungültiger reference_id still verworfen, die Ablehnung selbst bleibt. Umgekehrt gilt das nicht. Signalisiere eine Ablehnung nie über einen Fehlerstatus. Alles außer HTTP 200 mit lesbarem Verdict ist ein Webhook-Fehler, und dann greift dein Failure Handling statt deines Urteils.

Von der Antwort liest Anthropic höchstens 64 KiB, unkomprimiert. Weiterleitungen werden nicht verfolgt, Cookies ignoriert, unbekannte Felder im Verdict überlesen.

Signatur prüfen

Signiert wird nach der Standard-Webhooks-Spezifikation über drei Header. Anthropic schickt die Namen klein, Proxys dürfen sie umschreiben. Schlag sie also unabhängig von Groß- und Kleinschreibung nach.

Header	Inhalt
`webhook-id`	Eindeutige Kennung dieser Zustellung, identisch mit `request_id` im Body. Taugt als Idempotenzschlüssel und ist der erste Teil der signierten Nutzlast.
`webhook-timestamp`	Unix-Zeit in Sekunden als Dezimalstring. Liegt sie mehr als fünf Minuten von deiner Uhr entfernt, in eine der beiden Richtungen, lehne ab.
`webhook-signature`	Ein oder mehrere durch Leerzeichen getrennte Werte `v1,<base64>`, je ein HMAC-SHA256 über `{webhook-id}.{webhook-timestamp}.{rohe Body-Bytes}`. Akzeptiere, wenn einer passt, und vergleiche in konstanter Zeit.

Zwei Fehler machen fast alle Verifizierungsprobleme aus:

Über die rohen Bytes rechnen, also über den Body genau so, wie er ankam, vor jedem Parsen und Neuserialisieren.
Das Secret mit einem Standard-Base64-Dekoder lesen. Der Schlüssel ist der Teil nach dem Präfix whsec_, im Standard-Alphabet mit + und /. Ein URL-sicherer Dekoder liefert falsche Schlüsselbytes, sobald + oder / vorkommen, und das ist meistens der Fall.

Die Prüfung in Python, wie sie in der Doku steht:

import base64, hashlib, hmac, time

TOLERANCE_SECONDS = 300


def verify(secret: str, headers: dict[str, str], body: bytes) -> bool:
    lowercased = {name.lower(): value for name, value in headers.items()}
    try:
        message_id = lowercased["webhook-id"]
        timestamp = lowercased["webhook-timestamp"]
        signatures = lowercased["webhook-signature"]
    except KeyError:
        return False  # unsigniert: nicht von Anthropic

    try:
        signed_at = int(timestamp)
    except ValueError:
        return False
    if abs(time.time() - signed_at) > TOLERANCE_SECONDS:
        return False  # wiedereingespielt, oder die Uhren gehen auseinander

    try:
        key = base64.b64decode(secret.removeprefix("whsec_"), validate=True)
    except ValueError:
        return False

    payload = f"{message_id}.{timestamp}.".encode() + body
    expected = b"v1," + base64.b64encode(
        hmac.new(key, payload, hashlib.sha256).digest()
    )
    return any(
        hmac.compare_digest(expected, candidate.encode())
        for candidate in signatures.split()
    )

Sobald deine Organisation ein Secret hat, ist jede Anfrage signiert, auch der Verbindungstest; der Einrichtungsablauf erzeugt das Secret vor dem ersten Test. Unsignierte Anfragen also ablehnen. Eine Ausnahme gibt es: Organisationen, die Inference Hooks eingeschaltet haben, bevor das Secret Pflicht wurde, senden weiter unsigniert, bis ein Admin eins erzeugt.

Beim Rotieren wird sofort umgeschaltet, ohne Überlappung. Mit dem alten Secret signierte Anfragen treffen trotzdem noch etwa eine Minute lang ein, dazu alles, was schon unterwegs war. Lass deinen Server während des Wechsels beide Signaturen gelten.

Betrieb

Wiederholung: Genau einmal, nach 100 ms, und nur wenn schon der Verbindungsversuch scheitert. Der zweite Versuch teilt sich dasselbe Zeitbudget und trägt dieselbe webhook-id und dieselbe Signatur. Hat dein Server einmal geantwortet, wird nie wiederholt.
Doppelte erkennen: Über webhook-id. Wenn du Verdicts protokollierst, schlüssle die Einträge darauf.
Circuit Breaker: Anhaltende Fehler, die deinem Server zuzurechnen sind, lösen ihn aus. Dann kontaktiert Anthropic deinen Server nicht mehr, und dein Failure Handling gilt für jede Anfrage. Bei Block the request heißt das: Deine Leute sind blockiert, bis er zurückgesetzt ist. Ab 10 Minuten nach dem Auslösen prüft Anthropic höchstens etwa einmal pro Minute mit derselben synthetischen Testanfrage nach, ob dein Server wieder antwortet; ein gültiges Verdict, allow oder deny, setzt ihn zurück. Änderst du nach dem Auslösen irgendeine Einstellung, auch nur das Secret rotiert, hören diese Prüfungen auf. Dann schaltest du Enforce verdicts von Hand wieder ein.
Quell-IPs: Die Anfragen kommen aus 160.79.106.0/24, Teil der veröffentlichten ausgehenden Adressbereiche von Anthropic. Die eingehenden Bereiche auf derselben Seite decken das nicht ab. Eine Allowlist verkleinert die Angriffsfläche, ersetzt die Signaturprüfung aber nicht: Über den Block läuft auch anderer ausgehender Verkehr.
Latenz: Die Laufzeit deines Servers liegt auf jeder geprüften Anfrage der Organisation. Vor dem Rollout in eine große Organisation gehört der Server unter Last.

Vorwärtskompatibel bleiben

Das Protokoll wächst. Dein Server muss unbekannte Felder auf oberster Ebene, unbekannte Schlüssel in metadata, neue Werte in source.application, neue actor.type-Werte und Blöcke mit unbekanntem type überlesen, statt die Anfrage abzuweisen.

Ein Sonderfall: Weitere Ereignistypen sind angekündigt. Kommt oben ein type, den du nicht kennst, lässt sich das nicht durch Überspringen lösen, die Anfrage braucht trotzdem ein Verdict. Dann allow zurückgeben, keinen Fehlerstatus. Ein Fehler ist ein Webhook-Fehler, und anhaltende Webhook-Fehler lösen den Circuit Breaker aus.

Was der Nutzer beim Deny sieht

Die Meldung besteht aus zwei Teilen: dem deny_reason deines Servers, dann eine Leerzeile, dann ein feststehender Text, den Admins unter Custom blocked prompt message hinterlegen: bis zu 500 Zeichen, üblicherweise wen man anspricht oder wo man eine Ausnahme beantragt. Ohne eigenen Text verweist eine eingebaute Vorgabe auf die Administratoren; der angehängte Teil lässt sich auch ganz abschalten, dann steht dort nur der deny_reason.

Schreib den deny_reason deshalb für den Nutzer, nicht fürs eigene Team: was er ändern soll, welche Art Inhalt raus muss, und nicht ein Scanner-Code, den nur ihr entziffern könnt.

Jede Ablehnung landet außerdem im Activity Feed der Organisation. Eine blockierte Nachricht bleibt in der Unterhaltung auf claude.ai stehen; das Inference-Hooks-System selbst legt keine eigene Kopie von Prompts oder Antworten an, sondern nur Konfiguration und Metadaten wie Verdicts, Zeitstempel und Anfragekennungen.

Wer ausgenommen werden kann

Unter Exclusions wählst du Rollen, deren Mitglieder gar nicht erst erfasst werden: Ihre Prompts gehen nie an deinen Server. Angeboten werden nur selbst angelegte Rollen, keine eingebauten. Die Liste ist leer voreingestellt. Die Ausnahme gilt für die interaktiven Sitzungen einer Person; Verkehr, der sich mit Maschinen-Zugangsdaten ausweist, wird immer geprüft. Änderungen an der Liste stehen im Audit-Trail, und sie zu ändern verlangt die Berechtigung für Identitätsverwaltung.

Im Blick behalten

Der Bereich Endpoint health auf der Einstellungsseite zeigt Status (Healthy, Tripped, Not enforcing, Not configured), Fehler pro Minute als Mittel der letzten zwei Minuten, die Blockrate, solange der Rollout-Anteil unter 100 liegt, und wann der Circuit Breaker zuletzt ausgelöst hat. Die letzten Fehler stehen als Zeitstempel, Fehlerart und einzeiliger Grund da, ohne Inhalte und ohne deine Endpunkt-Adresse.

Zwei Einschränkungen nennt die Doku selbst: Die Anzeige arbeitet nach bestem Bemühen und zeigt null Fehler, wenn sie die Zähler nicht lesen kann. Eine gesunde Anzeige ist also kein Beleg für einen gesunden Server. Und die Fehler pro Minute zählen auch Netz- und DNS-Fehler mit, die den Circuit Breaker nie auslösen; der Wert kann hoch stehen, während bei Circuit breaker tripped nichts steht.

Wer alarmieren will, nimmt besser den Activity Feed: Jedes Auslösen steht dort als inference_hooks_circuit_breaker_tripped, eine Aktivität je Auslösung, nicht je betroffener Anfrage. Dafür muss die Compliance API für die Organisation eingeschaltet sein. Während der Breaker ausgelöst ist, werden keine Einzelaktivitäten mehr geschrieben, die Auslöse-Aktivität ist der einzige Eintrag für dieses Zeitfenster.

Wieder ausschalten

Zwei Stufen:

Enforce verdicts aus auf der Einstellungsseite. Innerhalb etwa einer Minute gehen keine Prompts mehr an deinen Server, laufende Anfragen beenden sich nach der alten Einstellung. Die Seite bleibt erreichbar. Das ist die Pause, während du am Server arbeitest.
Allow for your organization aus in den Data-and-privacy-Einstellungen. Dann ist auch die Einstellungsseite weg. Endpunkt, Header und Secret bleiben in beiden Fällen erhalten; beim Wiedereinschalten wird Enforce verdicts zwangsweise auf aus gesetzt und ein ausgelöster Circuit Breaker gelöscht.

Grenzen

Nur allow oder deny. Umschreiben oder Schwärzen eines Prompts geht nicht: Er geht ganz durch oder gar nicht.
Nur das Ereignis prompt. Es feuert einmal je geprüfter Inferenz-Anfrage, vor der Inferenz. Durchsetzung auf der Antwortseite ist als späteres Ereignis angekündigt, existiert aber noch nicht.
Anhänge kommen als Metadaten und extrahierter Text. Rohe Datei- und Bildbytes werden nie geschickt, reine Bildinhalte, der Screenshot eines Dokuments etwa, werden also nicht geprüft.
Nicht erfasst: Voice Mode, Nebenanfragen wie das Erzeugen von Unterhaltungstiteln, System-Prompts und Tool-Definitionen.
Nicht verfügbar: für Platform-Organisationen, auf Amazon Bedrock und auf Google Cloud.
Beta. Feldnamen, Request-Formate und Header können sich ändern. Dieser Guide wird beim nächsten Lauf gegen die Doku geprüft.

Wer nicht vorher eingreifen will, sondern hinterher nachsehen: Dafür ist die Compliance API da. Inference Hooks wirkt inline und entscheidet in Echtzeit, Anthropic ruft dabei deinen Server. Die Compliance API arbeitet im Nachhinein, und du rufst Anthropic.

Änderungen

2026-09-22: Erste Fassung. Jede Angabe gegen die Doku vom 22.09.2026 geprüft.

Quellen

Inference hooks (platform.claude.com)
Configure Inference hooks (platform.claude.com)
Develop an Inference hooks integration (platform.claude.com)
Inference hooks overview (support.claude.com)