Ganchos de chat
Os ganchos de chat do Docsbook são endpoints HTTPS seus que o chat de IA chama em torno de cada resposta. Use-os para aplicar uma regra definida pela sua equipe de conformidade, fornecer ao modelo um fato que apenas os seus sistemas conhecem ou espelhar todas as perguntas e respostas no seu próprio armazenamento — sem bifurcar o chat.
O que você obtém#
Três hooks, cada um com sua própria URL, configurados de forma independente:
| Hook | Quando é executado | Pode alterar a resposta? | Para que serve |
|---|---|---|---|
| Hook de pré-processamento | Antes de o modelo ser chamado, de forma bloqueante | Sim — bloquear a solicitação ou injetar contexto no prompt | Recusar uma pergunta; adicionar o plano, a região ou os sinalizadores de recursos do leitor |
| Hook de pós-processamento | Depois que a resposta é concluída | Não | Registrar o par pergunta/resposta no seu próprio armazenamento |
| Hook de streaming | Junto com o hook de pós-processamento | Não | Alimentar um painel em tempo real ou um canal de alertas |
Somente o hook de pré-processamento altera alguma coisa, pois é o único pelo qual o Docsbook espera. Os outros dois são disparados depois que o leitor já recebeu a resposta, e suas respostas nunca são lidas — eles não podem remover, reescrever ou reformatar o que foi exibido.
Os hooks estão disponíveis em todos os planos, e chamá-los não consome nada do seu saldo. As URLs devem ser https://; uma URL http:// é rejeitada quando você a salva.
Como uma pergunta é bloqueada ou enriquecida?#
Defina uma URL de pre-hook. O Docsbook faz POST da pergunta do leitor para ela como JSON e aguarda, depois age com base em dois campos opcionais da sua resposta.
O que o Docsbook envia:
{
"question": "What's the price for team@acme.com?",
"session_id": "sess_YOUR_SESSION_ID",
"workspace_id": 42
}O que o Docsbook entende na resposta:
{
"block": true,
"reason": "Ask your account manager for account-specific pricing",
"inject_context": "The reader is on the Acme account, locale en-GB."
}block: trueinterrompe a solicitação. Nenhum modelo é chamado e nenhum token é gasto. O fluxo transmite um erro deblocked_by_hookcom seureason— mas veja abaixo o limite do que o leitor realmente vê.inject_contexté adicionado ao prompt como uma mensagem de sistema extra para esta pergunta, depois do seu próprio prompt de sistema e antes da própria pergunta. É aqui que entram os fatos atuais: o plano do leitor, a região dele, uma flag de recurso.- Qualquer outra coisa — um status não-2xx, JSON impossível de analisar, um corpo vazio ou nenhuma resposta dentro do tempo limite — e o chat continua exatamente como se nenhum hook estivesse definido. Um hook com falha degrada o chat; ele não o interrompe.
Os três hooks compartilham um tempo limite de 5 segundos, aplicado ao abortar a solicitação. O tempo limite do pre-hook custa esses segundos ao leitor uma vez; os outros dois não lhe custam nada, porque a resposta já foi transmitida.
O que o post-hook recebe#
Um POST, depois de o leitor já ter visto a resposta:
{
"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 é uma entrada por página que o servidor realmente buscou para esta pergunta, na ordem em que as leu — a mesma lista que o leitor viu como linhas Reading <page>. É um registro da recuperação, não do uso das próprias ferramentas pelo modelo.
O hook de streaming recebe event: "message", question, answer, refs (as citações que sobreviveram à filtragem), workspace_id, session_id e latency_ms. Ele não inclui tool_calls; o post-hook é que o faz.
Qual hook para qual tarefa#
| Cenário | Hook | Por que esse |
|---|---|---|
| Recusar perguntas sobre a conta de outro cliente | Pre-hook | Apenas o pre-hook pode interromper a solicitação |
| Fornecer ao modelo o plano e a localidade do leitor | Pre-hook (inject_context) |
O modelo precisa disso antes de responder |
| Espelhar cada interação na sua própria base de análise | Post-hook | Precisa da resposta concluída e não altera nada |
| Alertar um canal quando uma resposta demora demais | Streaming ou post-hook | Ambos carregam latency_ms |
| Testar duas formulações de prompt em A/B | Pre-hook | Modifica o prompt, uma pergunta por vez |
| Garantir que uma string nunca chegue ao leitor | Pre-hook ou o prompt do sistema | O post-hook é executado depois que o leitor já a recebeu |
Os hooks de chat são assinados?#
Não. O Docsbook envia um POST simples com Content-Type: application/json e sem um cabeçalho HMAC, portanto seu endpoint não deve tratar o payload como prova de origem. Mantenha a URL em segredo, coloque um token no caminho ou na string de consulta, restrinja o acesso à saída do Docsbook e trate o corpo como uma entrada não confiável.
Os webhooks do Docsbook são um mecanismo diferente e são assinados: HMAC-SHA256 sobre o corpo bruto em X-Docsbook-Signature-256, conforme sha256=<hex>. Não reutilize o código de verificação de um webhook em um hook de chat presumindo que ele verifica alguma coisa — ele será aprovado com um corpo que qualquer pessoa poderia ter enviado.
Gerenciando hooks de um cliente MCP#
Três ferramentas configuram hooks do Claude Code, Cursor ou qualquer cliente 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 promptPasse uma string vazia para set_chat_hooks para limpar um hook individual. test_chat_hook envia { test: true, hook_type, workspace_id, timestamp, message } e informa o código de status e o tempo de ida e volta, usando o mesmo tempo limite de 5 segundos usado pelo fluxo ativo. Os mesmos campos podem ser editados no painel de administração.
Por que esta é a maneira certa (evidências)#
| Regra | Por que funciona | Fonte |
|---|---|---|
| Injete fatos atuais por meio do pré-hook em vez de permitir que o modelo os recupere da memória | A geração aumentada por recuperação produz "linguagem mais específica, diversificada e factual do que uma linha de base paramétrica exclusiva de última geração" — um fato colocado no prompt é fundamentado; um fato recuperado da memória não é | Lewis et al., 2020 — RAG |
| Bloqueie no pré-hook, não por pós-processamento | A instrução, por si só, não impede de forma confiável que um modelo responda: o ajuste comum "força o modelo a completar uma frase, independentemente de o modelo conhecer ou não o conhecimento". Uma recusa que você pode garantir é aquela que nunca chega ao modelo | Zhang et al., 2023 — R-Tuning |
| Trate um payload de hook não assinado como não confiável | Uma assinatura é o que comprova a origem: "para garantir que seu servidor processe apenas entregas de webhook enviadas pelo GitHub e garantir que a entrega não tenha sido adulterada, você deve validar a assinatura do webhook". Os hooks de chat não têm nenhuma, portanto autentique-os por conta própria | GitHub — Validando entregas de webhook |
| Compare a assinatura do webhook do Docsbook em tempo constante | "Nunca use um operador simples ==. Em vez disso, considere usar um método como secure_compare ou crypto.timingSafeEqual" |
GitHub — Validando entregas de webhook |
Limites#
- O leitor não vê o motivo do bloqueio. A string
reasoné enviada no fluxo de resposta, mas o widget do site de documentação substitui-a pela mensagem genérica "Something went wrong. Please try again." Em questão: o valor está na transmissão e um front-end personalizado pode lê-lo, mas o widget que você recebe pronto não o exibe. Tratereasoncomo um valor para os seus logs e coloque no seu prompt do sistema tudo o que o leitor precisar ler. - Os hooks não são executados no caminho de pré-visualização anônima. Um repositório pré-visualizado antes de ter uma linha de projeto responde às perguntas sem um workspace, e o pré-hook é ignorado junto com todas as outras ramificações por projeto.
- Não há novas tentativas nem registro de entrega. Os hooks de pós-processamento e de streaming são despachados uma vez, e o resultado não é registrado. Se você precisa de entrega pelo menos uma vez, com novas tentativas e um histórico de entregas visível, use webhooks, que oferecem ambos.
- Não há assinatura, nem planos de adicionar uma antes que o esquema dos webhooks seja reutilizado. Consulte acima.
set_chat_hooksetest_chat_hookainda se descrevem como exigindo o plano Pro. A capacidade que eles verificam está disponível em todos os planos, portanto as descrições das ferramentas estão desatualizadas, e não o comportamento. Isso continuará sendo uma questão até que essas strings sejam corrigidas.- Um pré-hook lento é custeado pelo leitor. Cinco segundos é o limite, e isso ocorre antes do primeiro token. Mantenha o endpoint rápido ou não retorne nada e permita que o chat continue.
Relacionado#
- Chat de IA — o contrato ao qual os hooks se conectam.
- Qualidade das respostas — onde cada hook se posiciona no pipeline.
- Fontes — a outra forma de fornecer ao assistente fatos que ele não possui.
- Webhooks — entregas assinadas, com novas tentativas e orientadas por eventos.
- Servidor MCP — configure hooks remotamente a partir do seu editor.