Chat-Hooks

Docsbook-Chat-Hooks sind HTTPS-Endpunkte von Ihnen, die der KI-Chat rund um jede Antwort aufruft. Verwenden Sie sie, um eine von Ihrem Compliance-Team verfasste Regel durchzusetzen, dem Modell eine Tatsache bereitzustellen, die nur Ihre Systeme kennen, oder jede Frage und Antwort in Ihren eigenen Speicher zu spiegeln – ohne den Chat zu forken.

Was Sie erhalten#

Drei Hooks, jeder mit einer eigenen URL, die jeweils unabhängig konfiguriert werden:

Hook	Wann er ausgeführt wird	Kann er die Antwort ändern?	Wofür er gedacht ist
Pre-Hook	Bevor das Modell aufgerufen wird, blockierend	Ja — die Anfrage blockieren oder Kontext in den Prompt einfügen	Eine Frage ablehnen; den Plan, die Region oder die Feature-Flags des Lesers hinzufügen
Post-Hook	Nachdem die Antwort vollständig ist	Nein	Das Frage-Antwort-Paar im eigenen Speicher protokollieren
Streaming-Hook	Zusammen mit dem Post-Hook	Nein	Ein Live-Dashboard oder einen Alarmierungskanal versorgen

Nur der Pre-Hook ändert etwas, da nur auf ihn Docsbook wartet. Die anderen beiden werden gesendet, nachdem der Leser die Antwort bereits erhalten hat, und ihre Antworten werden nie gelesen — sie können das Angezeigte nicht schwärzen, umschreiben oder neu formatieren.

Hooks sind in jedem Tarif verfügbar, und ihr Aufruf wird nicht von Ihrem Guthaben abgezogen. URLs müssen https:// sein; eine http://-URL wird beim Speichern abgelehnt.

Wie wird eine Frage blockiert oder angereichert?#

Legen Sie eine Pre-Hook-URL fest. Docsbook sendet die Frage des Lesers als JSON dorthin und wartet anschließend. Danach verarbeitet es zwei optionale Felder Ihrer Antwort.

Was Docsbook sendet:

{
  "question": "What's the price for team@acme.com?",
  "session_id": "sess_YOUR_SESSION_ID",
  "workspace_id": 42
}

Was Docsbook als Antwort versteht:

{
  "block": true,
  "reason": "Ask your account manager for account-specific pricing",
  "inject_context": "The reader is on the Acme account, locale en-GB."
}

block: true stoppt die Anfrage. Es wird kein Modell aufgerufen und es werden keine Tokens verbraucht. Der Stream enthält einen Fehler von blocked_by_hook mit Ihrem reason — beachten Sie jedoch die folgende Einschränkung dessen, was der Leser tatsächlich sieht.
inject_context wird für diese eine Frage als zusätzliche Systemnachricht zum Prompt hinzugefügt, nach Ihrem eigenen System-Prompt und vor der eigentlichen Frage. Hier gehören aktuelle Informationen hinein: der Tarif des Lesers, seine Region oder ein Feature-Flag.
Alles andere — ein Nicht-2xx-Status, nicht parsebares JSON, ein leerer Antworttext oder keine Antwort innerhalb des Timeouts — und der Chat wird genau so fortgesetzt, als wäre kein Hook festgelegt. Ein fehlerhafter Hook beeinträchtigt den Chat, bringt ihn aber nicht zum Absturz.

Alle drei Hooks haben ein gemeinsames 5-Sekunden-Timeout, das durch Abbrechen der Anfrage durchgesetzt wird. Das Timeout des Pre-Hooks kostet den Leser diese Sekunden einmalig; die beiden anderen kosten ihn nichts, da die Antwort bereits gestreamt wurde.

Was der Post-Hook empfängt#

Ein POST, nachdem der Leser die Antwort bereits gesehen hat:

{
  "question": "How do I rotate an API key?",
  "answer": "Rotate an API key in Workspace settings…",
  "tool_calls": [{ "tool": "read_page", "path": "guides/keys.md" }],
  "latency_ms": 2840,
  "workspace_id": 42,
  "session_id": "sess_YOUR_SESSION_ID"
}

tool_calls ist ein Eintrag pro Seite, die der Server tatsächlich für diese Frage abgerufen hat, in der Reihenfolge, in der er sie gelesen hat – dieselbe Liste, die der Leser als Reading <page>-Zeilen gesehen hat. Es handelt sich um ein Protokoll des Abrufs, nicht um eine Aufzeichnung der eigenen Tool-Nutzung des Modells.

Der Streaming-Hook empfängt event: "message", question, answer, refs (die Zitate, die die Filterung überstanden haben), workspace_id, session_id und latency_ms. Er enthält tool_calls nicht; dafür ist der Post-Hook zuständig.

Welcher Hook für welche Aufgabe#

Szenario	Hook	Warum dieser
Fragen zum Konto eines anderen Kunden ablehnen	Pre-Hook	Nur der Pre-Hook kann die Anfrage stoppen
Dem Modell den Plan und das Gebietsschema des Lesers geben	Pre-Hook (`inject_context`)	Das Modell benötigt diese Informationen, bevor es antwortet
Jeden Austausch in den eigenen Analysespeicher spiegeln	Post-Hook	Benötigt die fertige Antwort und ändert nichts
Einen Kanal benachrichtigen, wenn eine Antwort zu lange dauert	Streaming oder Post-Hook	Beide übertragen `latency_ms`
Zwei Prompt-Formulierungen A/B-testen	Pre-Hook	Verändert den Prompt, eine Frage nach der anderen
Garantieren, dass eine Zeichenfolge niemals einen Leser erreicht	Pre-Hook oder System-Prompt	Der Post-Hook läuft, nachdem der Leser sie erhalten hat

Sind Chat-Hooks signiert?#

Nein. Docsbook sendet ein einfaches POST mit Content-Type: application/json und ohne HMAC-Header, daher darf dein Endpunkt die Nutzdaten nicht als Beweis für ihre Herkunft behandeln. Halte die URL geheim, füge einen Token in ihren Pfad oder ihre Abfragezeichenfolge ein, beschränke den Zugriff auf den Egress von Docsbook und behandle den Inhalt als nicht vertrauenswürdige Eingabe.

Die Webhooks von Docsbook sind ein anderer Mechanismus und sind signiert: HMAC-SHA256 über den Rohinhalt in X-Docsbook-Signature-256, wie in sha256=<hex>. Übertrage den Verifizierungscode eines Webhooks nicht auf einen Chat-Hook und gehe davon aus, dass er irgendetwas verifiziert – er wird bei einem Inhalt bestehen, den jeder hätte senden können.

Hooks von einem MCP-Client verwalten#

Drei Tools konfigurieren Hooks von Claude Code, Cursor oder jedem MCP-Client:

set_chat_hooks          # register pre / post / streaming hook URLs
test_chat_hook          # send a test ping to one hook and report its status
get_chat_system_prompt  # inspect the current system prompt

Übergeben Sie set_chat_hooks eine leere Zeichenfolge, um einen einzelnen Hook zu löschen. test_chat_hook sendet { test: true, hook_type, workspace_id, timestamp, message } und meldet den Statuscode sowie die Round-Trip-Zeit unter Verwendung desselben 5-Sekunden-Timeouts wie der Live-Pfad. Dieselben Felder können im Admin-Panel bearbeitet werden.

Warum dies der richtige Weg ist (Belege)#

Regel	Warum es funktioniert	Quelle
Aktuelle Fakten über den Pre-Hook injizieren, statt das Modell sie erinnern zu lassen	Retrieval-augmented Generation erzeugt „spezifischere, vielfältigere und faktischere Sprache als eine hochmoderne rein parametrische“ Baseline — ein in den Prompt eingefügter Fakt ist fundiert; ein abgerufener Fakt ist es nicht	Lewis et al., 2020 — RAG
Im Pre-Hook blockieren, nicht durch Nachbearbeitung	Eine Anweisung allein hindert ein Modell nicht zuverlässig am Antworten: Gewöhnliches Tuning „zwingt das Modell, einen Satz zu vervollständigen, unabhängig davon, ob das Modell über das Wissen verfügt oder nicht“. Eine Verweigerung, die Sie garantieren können, ist eine, die das Modell nie erreicht	Zhang et al., 2023 — R-Tuning
Eine nicht signierte Hook-Nutzlast als nicht vertrauenswürdig behandeln	Eine Signatur beweist die Herkunft: „Um sicherzustellen, dass Ihr Server nur Webhook-Zustellungen verarbeitet, die von GitHub gesendet wurden, und dass die Zustellung nicht manipuliert wurde, sollten Sie die Webhook-Signatur validieren.“ Chat-Hooks enthalten keine, daher müssen Sie sie selbst authentifizieren	GitHub — Webhook-Zustellungen validieren
Die Webhook-Signatur von Docsbook in konstanter Zeit vergleichen	„Verwenden Sie niemals den einfachen `==`-Operator. Ziehen Sie stattdessen eine Methode wie `secure_compare` oder `crypto.timingSafeEqual` in Betracht“	GitHub — Webhook-Zustellungen validieren

Einschränkungen#

Der Leser sieht den Grund für die Sperrung nicht. Die Zeichenkette reason wird im Antwort-Stream übertragen, aber das ausgelieferte Docs-Site-Widget ersetzt sie durch seine generische Meldung „Etwas ist schiefgelaufen. Bitte versuchen Sie es erneut.“ Zur Klarstellung: Der Wert wird übertragen und ein eigenes Frontend kann ihn auslesen, aber das standardmäßig bereitgestellte Widget zeigt ihn nicht an. Behandeln Sie reason als Wert für Ihre Protokolle und fügen Sie alles, was der Leser lesen muss, stattdessen in Ihren System-Prompt ein.
Hooks werden im anonymen Vorschaupfad nicht ausgeführt. Ein Repository, das in der Vorschau angezeigt wird, bevor es einen Projekte’intrag hat, beantwortet Fragen ohne Workspace, und der Pre-Hook wird zusammen mit allen anderen projektspezifischen Zweigen übersprungen.
Keine Wiederholungsversuche und kein Zustellungsprotokoll. Post- und Streaming-Hooks werden einmal ausgelöst, und ihr Ergebnis wird nicht aufgezeichnet. Wenn Sie eine mindestens einmalige Zustellung mit Wiederholungsversuchen und einer sichtbaren Zustellhistorie benötigen, verwenden Sie Webhooks, die beides bieten.
Keine Signatur und kein Plan, eine solche hinzuzufügen, bevor das Schema der Webhooks wiederverwendet wird. Siehe oben.
set_chat_hooks und test_chat_hook beschreiben sich weiterhin als Pro-pflichtig. Die von ihnen geprüfte Funktion ist in jedem Tarif verfügbar, daher sind die Toolbeschreibungen veraltet und nicht das Verhalten. Bis diese Zeichenketten korrigiert sind, sollte dies berücksichtigt werden.
Ein langsamer Pre-Hook geht zulasten des Lesers. Fünf Sekunden sind die Obergrenze, und sie verstreichen vor dem ersten Token. Halten Sie den Endpunkt schnell oder geben Sie nichts zurück und lassen Sie den Chat fortfahren.

KI-Chat — der Vertrag, in den die Hooks eingebunden werden.
Antwortqualität — wo sich die einzelnen Hooks in der Pipeline befinden.
Quellen — die andere Möglichkeit, dem Assistenten ihm nicht bekannte Fakten bereitzustellen.
Webhooks — signierte, wiederholte, ereignisgesteuerte Übermittlungen.
MCP-Server — Hooks remote aus Ihrem Editor konfigurieren.

Updated Sep 5, 2026