チャットフック

Docsbookのチャットフックは、AIチャットが各回答の前後に呼び出す、皆様が用意したHTTPSエンドポイントです。コンプライアンスチームが策定したルールの適用、皆様のシステムだけが把握している事実のモデルへの提供、すべての質問と回答の独自ストアへのミラーリングなどを、チャットをフォークせずに実行できます。

得られるもの#

それぞれ固有のURLを持ち、個別に設定できる3つのフック：

変更を加えられるのは、Docsbookが完了を待つ唯一のフックであるため、プレフックだけです。他の2つは読者がすでに回答を受け取った後にディスパッチされ、レスポンスが読み取られることはありません。そのため、表示された内容を伏せ字にしたり、書き換えたり、形式を変更したりすることはできません。

フックはすべてのプランで利用でき、呼び出しても残高は一切消費されません。URLは https:// でなければならず、http:// URLは保存時に拒否されます。

質問はどのようにブロックまたは拡張されますか？#

pre-hook URLを設定します。Docsbookは読者の質問をJSONとしてそのURLにPOSTし、応答を待機してから、返信に含まれる2つの任意フィールドに基づいて処理します。

Docsbookが送信する内容：

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

Docsbookが受け付ける応答：

{
  "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 はリクエストを停止します。モデルは呼び出されず、トークンも消費されません。ストリームには、blocked_by_hook のエラーと、設定した reason が含まれます。ただし、読者に実際に表示される内容については、以下の制限を参照してください。
• inject_context は、この質問に限り、追加のシステムメッセージとしてプロンプトに追加されます。追加位置は、独自のシステムプロンプトの後、質問自体の前です。読者のプラン、地域、機能フラグなど、リアルタイムの情報を指定する場所です。
• その他すべて — 2xx以外のステータス、解析できないJSON、空の本文、またはタイムアウトまでに返信がない場合 — フックが設定されていない場合とまったく同じようにチャットが続行されます。フックが壊れていてもチャットの機能が低下するだけで、停止することはありません。

3つのフックすべてに5秒のタイムアウトが設定されており、リクエストを中止することで適用されます。pre-hookのタイムアウトでは読者がその5秒を一度待つことになりますが、他の2つでは回答がすでにストリーミングされているため、読者は時間を失いません。

post-hook が受け取るもの#

読者がすでに回答を見た後の、1回のPOST:

{
  "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 は、この質問のためにサーバーが実際に取得したページごとに1つのエントリで構成され、サーバーがページを読み取った順序になっています。つまり、読者が Reading <page> 行として見たものと同じリストです。これはモデル自身のツール使用ではなく、取得の記録です。

ストリーミングフックは、event: "message"、question、answer、refs（フィルタリングを通過した引用）、workspace_id、session_id、latency_ms を受け取ります。tool_calls は含まれません。これを行うのは post-hook です。

どの仕事にどのフックを使うか#

チャットフックには署名がありますか？#

いいえ。Docsbook は Content-Type: application/json を含むプレーンな POST を送信し、HMAC ヘッダーも付けないため、エンドポイントでペイロードを送信元の証明として扱ってはいけません。URL は秘密にし、そのパスまたはクエリ文字列にトークンを含め、Docsbook の送信元に限定し、本文は信頼できない入力として扱ってください。

Docsbook のウェブフックは別の仕組みで、署名されています。sha256=<hex> のとおり、X-Docsbook-Signature-256 における生の本文に対する HMAC-SHA256 です。ウェブフックの検証コードをチャットフックに流用して、何かを検証できると思わないでください。誰でも送信できる本文でも通過してしまいます。

MCP クライアントからのフックの管理#

Claude Code、Cursor、または任意の MCP クライアントからフックを設定する 3 つのツールがあります。

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

個々のフックをクリアするには、set_chat_hooks に空の文字列を渡します。test_chat_hook は { test: true, hook_type, workspace_id, timestamp, message } を POST し、ステータスコードとラウンドトリップ時間を報告します。ライブパスで使用されるものと同じ 5 秒のタイムアウトが適用されます。管理パネルでも同じフィールドを編集できます。

これが正しい方法である理由（根拠）#

制限#

• 読者にはブロック理由が表示されません。 reason 文字列はレスポンスストリームで配信されますが、提供される docs-site ウィジェットでは汎用的な「問題が発生しました。もう一度お試しください。」に置き換えられます。つまり、この値は通信上に存在し、カスタムフロントエンドから読み取ることはできますが、標準で提供されるウィジェットには表示されません。reason はログ用の値として扱い、読者に必ず読ませる必要がある内容は、代わりにシステムプロンプトに記述してください。
• 匿名プレビューのパスではフックは実行されません。 プロジェクト行が作成される前にプレビューされたリポジトリでは、ワークスペースなしで質問に回答するため、プロジェクト単位の他のすべての分岐と同様にプレフックもスキップされます。
• 再試行も配信ログもありません。 Post フックとストリーミングフックは一度だけディスパッチされ、その結果は記録されません。少なくとも1回の配信、再試行、そして確認可能な配信履歴が必要な場合は、これらすべてを備えたwebhookを使用してください。
• 署名はなく、webhook の方式が再利用されるまでは追加する予定もありません。 上記を参照してください。
• set_chat_hooks と test_chat_hook は、依然として Pro が必要だと説明しています。 これらが確認する機能はすべてのプランで利用可能なため、古いのは動作ではなくツールの説明です。これらの文字列が修正されるまでは、未解決の問題として扱ってください。
• 遅いプレフックの負担を負うのは読者です。 上限は5秒で、最初のトークンより前に発生します。エンドポイントを高速に保つか、何も返さずにチャットを続行させてください。

関連#

• AIチャット — フックが接続する契約。
• 回答品質 — 各フックがパイプラインのどこに位置するか。
• ソース — アシスタントが持っていない事実を提供するもう1つの方法。
• Webhooks — 署名付きで再試行される、イベント駆動型の配信。
• MCPサーバー — エディターからリモートでフックを設定します。