Hooks de chat

Les hooks de chat de Docsbook sont des points de terminaison HTTPS qui vous appartiennent et que le chat IA appelle autour de chaque réponse. Utilisez-les pour appliquer une règle rédigée par votre équipe de conformité, transmettre au modèle un fait que seuls vos systèmes connaissent ou répliquer chaque question et réponse dans votre propre espace de stockage, sans créer de branche du chat.

Ce que vous obtenez#

Trois hooks, chacun avec sa propre URL, chacun configuré indépendamment :

Hook	Quand s’exécute-t-il	Peut-il modifier la réponse ?	À quoi sert-il
Hook préalable	Avant l’appel au modèle, de manière bloquante	Oui — bloquer la requête ou injecter du contexte dans le prompt	Refuser une question ; ajouter le forfait, la région ou les indicateurs de fonctionnalité du lecteur
Hook postérieur	Une fois la réponse terminée	Non	Consigner la paire question/réponse dans votre propre stockage
Hook de diffusion	En parallèle du hook postérieur	Non	Alimenter un tableau de bord en temps réel ou un canal d’alerte

Seul le hook préalable modifie quoi que ce soit, car c’est le seul pour lequel Docsbook attend une réponse. Les deux autres sont envoyés une fois que le lecteur a déjà reçu la réponse, et leurs réponses ne sont jamais lues — ils ne peuvent pas caviarder, réécrire ou reformater ce qui a été affiché.

Les hooks sont disponibles avec tous les forfaits, et leur appel ne prélève rien de votre solde. Les URL doivent être https:// ; une URL http:// est rejetée lorsque vous l’enregistrez.

Comment une question est-elle bloquée ou enrichie ?#

Définissez une URL de pré-interception. Docsbook lui envoie la question du lecteur au format JSON via POST et attend, puis agit sur deux champs facultatifs de votre réponse.

Ce que Docsbook envoie :

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

Ce que Docsbook comprend en retour :

{
  "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 arrête la requête. Aucun modèle n'est appelé et aucun jeton n'est consommé. Le flux contient une erreur de blocked_by_hook avec votre reason — mais consultez ci-dessous la limite concernant ce que le lecteur voit réellement.
inject_context est ajouté à l'invite sous forme de message système supplémentaire pour cette question uniquement, après votre propre invite système et avant la question elle-même. C'est ici que les informations en temps réel doivent être placées : le forfait du lecteur, sa région, un indicateur de fonctionnalité.
Tout le reste — un statut autre que 2xx, un JSON impossible à analyser, un corps vide ou l'absence de réponse dans le délai imparti — et la conversation continue exactement comme si aucun hook n'était défini. Un hook défaillant dégrade la conversation, mais ne la rompt pas.

Les trois hooks partagent un délai d'expiration de 5 secondes, appliqué en interrompant la requête. Le délai d'expiration du pré-hook coûte ces secondes au lecteur une seule fois ; les deux autres ne lui coûtent rien, car la réponse a déjà été diffusée.

Ce que reçoit le post-hook#

Un POST, après que le lecteur a déjà vu la réponse :

{
  "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 correspond à une entrée par page que le serveur a effectivement récupérée pour cette question, dans l'ordre où il les a lues — la même liste que le lecteur a vue sous forme de lignes Reading <page>. Il s'agit d'un relevé de la récupération, et non de l'utilisation de ses propres outils par le modèle.

Le hook de streaming reçoit event: "message", question, answer, refs (les citations qui ont survécu au filtrage), workspace_id, session_id et latency_ms. Il ne contient pas tool_calls ; c'est le post-hook qui s'en charge.

Quel hook pour quelle tâche#

Scénario	Hook	Pourquoi celui-ci
Refuser les questions concernant le compte d’un autre client	Pré-hook	Seul le pré-hook peut arrêter la requête
Fournir au modèle le forfait et les paramètres régionaux du lecteur	Pré-hook (`inject_context`)	Le modèle en a besoin avant de répondre
Répliquer chaque échange dans votre propre système de stockage analytique	Post-hook	Nécessite la réponse terminée, ne modifie rien
Alerter un canal lorsqu’une réponse prend trop de temps	Streaming ou post-hook	Les deux transmettent `latency_ms`
Tester A/B deux formulations de prompt	Pré-hook	Modifie le prompt, une question à la fois
Garantir qu’une chaîne n’atteint jamais un lecteur	Pré-hook ou prompt système	Le post-hook s’exécute après que le lecteur l’a reçue

Les hooks de chat sont-ils signés ?#

Non. Docsbook envoie un POST brut avec Content-Type: application/json et sans en-tête HMAC. Votre point de terminaison ne doit donc pas considérer la charge utile comme une preuve de son origine. Gardez l’URL secrète, placez un jeton dans son chemin ou sa chaîne de requête, limitez l’accès aux adresses de sortie de Docsbook et considérez le corps comme une entrée non fiable.

Les webhooks de Docsbook sont un mécanisme différent et sont signés : HMAC-SHA256 sur le corps brut dans X-Docsbook-Signature-256, comme indiqué dans sha256=<hex>. Ne réutilisez pas le code de vérification d’un webhook pour un hook de chat en supposant qu’il vérifie quoi que ce soit : il réussira avec un corps que n’importe qui aurait pu envoyer.

Gérer les hooks depuis un client MCP#

Trois outils configurent les hooks depuis Claude Code, Cursor ou n’importe quel client MCP :

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

Transmettez une chaîne vide à set_chat_hooks pour effacer un hook individuel. test_chat_hook envoie { test: true, hook_type, workspace_id, timestamp, message } et indique le code d’état ainsi que le temps aller-retour, en utilisant le même délai d’expiration de 5 secondes que le chemin en direct. Les mêmes champs sont modifiables dans le panneau d’administration.

Pourquoi c’est la bonne méthode (preuves)#

Règle	Pourquoi cela fonctionne	Source
Injecter les faits actuels via le pre-hook plutôt que de laisser le modèle s’en souvenir	La génération augmentée par récupération produit un langage « plus précis, diversifié et factuel qu’une référence uniquement paramétrique à la pointe de la technologie » — un fait placé dans le prompt est fondé ; un fait dont le modèle se souvient ne l’est pas	Lewis et al., 2020 — RAG
Bloquer au niveau du pre-hook, et non par post-traitement	Une instruction seule n’empêche pas de manière fiable un modèle de répondre : l’ajustement ordinaire « force le modèle à terminer une phrase, que le modèle connaisse ou non l’information ». Un refus que vous pouvez garantir est un refus qui n’atteint jamais le modèle	Zhang et al., 2023 — R-Tuning
Considérer la charge utile d’un hook non signé comme non fiable	Une signature est ce qui prouve l’origine : « pour garantir que votre serveur ne traite que les livraisons de webhook envoyées par GitHub et que la livraison n’a pas été altérée, vous devez valider la signature du webhook ». Les hooks de chat n’en ont aucune ; authentifiez-les donc vous-même	GitHub — Validation des livraisons de webhook
Comparer la signature de webhook de Docsbook en temps constant	« N’utilisez jamais un opérateur `==` simple. Envisagez plutôt d’utiliser une méthode comme `secure_compare` ou `crypto.timingSafeEqual` »	GitHub — Validation des livraisons de webhook

Limites#

Le lecteur ne voit pas la raison du blocage. La chaîne reason est envoyée dans le flux de réponse, mais le widget du site de documentation livré avec le produit la remplace par son message générique « Une erreur s’est produite. Veuillez réessayer. » En question : la valeur est bien transmise et un front-end personnalisé peut la lire, mais le widget fourni par défaut ne l’affiche pas. Considérez reason comme une valeur destinée à vos journaux, et placez dans votre invite système tout ce que le lecteur doit lire.
Les hooks ne s’exécutent pas sur le chemin de prévisualisation anonyme. Un dépôt prévisualisé avant d’avoir une ligne de projet répond aux questions sans espace de travail, et le hook préalable est ignoré, comme toutes les autres branches propres à chaque projet.
Aucune nouvelle tentative ni journal de livraison. Les hooks postérieurs et de streaming sont exécutés une seule fois et leur résultat n’est pas enregistré. Si vous avez besoin d’une livraison au moins une fois avec des nouvelles tentatives et un historique de livraison visible, utilisez les webhooks, qui offrent ces deux fonctionnalités.
Aucune signature, et aucun projet d’en ajouter une avant la réutilisation du schéma des webhooks. Voir ci-dessus.
set_chat_hooks et test_chat_hook indiquent toujours eux-mêmes qu’ils nécessitent Pro. La fonctionnalité qu’ils vérifient est ouverte à tous les forfaits ; ce sont donc les descriptions des outils qui sont obsolètes, et non le comportement. En question jusqu’à la correction de ces chaînes.
Un hook préalable lent est payé par le lecteur. Cinq secondes est le délai maximal, et il s’écoule avant le premier jeton. Gardez le point de terminaison rapide, ou ne renvoyez rien et laissez la conversation se poursuivre.

Chat IA — le contrat auquel les hooks se connectent.
Qualité des réponses — l’emplacement de chaque hook dans le pipeline.
Sources — l’autre moyen de fournir à l’assistant des informations qu’il ne possède pas.
Webhooks — des livraisons signées, réessayées et déclenchées par des événements.
Serveur MCP — configurez les hooks à distance depuis votre éditeur.

Updated Sep 5, 2026