Desenvolver uma integração de Inference hooks

Uma integração de Inference hooks é um servidor de segurança de IA: um serviço HTTPS que a Anthropic chama. Para cada requisição governada, seu servidor recebe um POST assinado contendo a transcrição da conversa e responde com um veredito de permissão ou negação. Esta página documenta o protocolo para construir esse servidor: os esquemas de requisição e veredito, a verificação de assinatura e o contrato operacional.

Para ativar os Inference hooks e apontá-los para seu endpoint, consulte Configurar Inference hooks. Para saber o que são Inference hooks e quando usá-los, consulte a visão geral de Inference hooks.



Obtenha seu primeiro ciclo completo de veredito

A menor integração funcional é um servidor que lê cada requisição e a permite. Execute um dos servidores a seguir, exponha-o em uma URL pública https:// (por exemplo, atrás de um proxy reverso com terminação TLS ou de um túnel) e, em seguida, peça ao seu administrador para defini-lo como o endpoint e testar a conexão: o resultado de Test connection informa o veredito de permissão que seu servidor retornou.

# Execute com: python server.py
from http.server import BaseHTTPRequestHandler, ThreadingHTTPServer


class VerdictHandler(BaseHTTPRequestHandler):
    protocol_version = "HTTP/1.1"  # keep the connection open between verdicts

    def do_POST(self):
        # Drene o corpo; transcrições podem ter megabytes.
        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()



Receber uma requisição

A Anthropic envia um POST HTTPS para a URL que seu administrador configura. A URL configurada inteira é o endpoint: não há sufixo de caminho fixo, então escolha qualquer caminho que seja adequado ao seu servidor.

Hospede seu servidor de segurança de IA onde a Anthropic possa alcançá-lo: uma URL https:// na porta 443, em um host publicamente roteável (intervalos privados, de loopback e de NAT de nível de operadora são recusados no momento da conexão), com um certificado que valide contra o repositório público de confiança de CA, respondendo sem redirecionamentos. A URL configurada deve ser o destino final. Configurar Inference hooks aborda como seu administrador define e testa a URL.

Toda requisição carrega estes cabeçalhos fixos, junto com quaisquer cabeçalhos de requisição personalizados que seu administrador configurou e, uma vez que sua organização tenha um segredo de assinatura, os cabeçalhos de assinatura webhook-* descritos em Verificar a assinatura:

Existe um evento de hook atualmente: o prompt frame, enviado uma vez por requisição de inferência governada, antes do início da inferência. A Anthropic retém a requisição até que seu servidor de segurança de IA responda ou o tempo limite do veredito expire.



O prompt frame

O corpo da requisição é um objeto JSON com estes campos:

Um exemplo de corpo de requisição:

{
  "type": "prompt",
  "request_id": "req_abc123",
  "tenant_id": "11111111-1111-1111-1111-111111111111",
  "actor": {
    "type": "user",
    "id": "user_01AbCdEfGhIjKlMnOpQrStUv",
    "email_address": "[email protected]"
  },
  "source": {
    "application": "claude-ai"
  },
  "session_id": "22222222-2222-2222-2222-222222222222",
  "model": "claude-sonnet-4-5",
  "messages": [
    {
      "role": "user",
      "content": [
        {
          "type": "text",
          "text": "Summarize the attached report."
        },
        {
          "type": "attachment",
          "file_name": "q2-report.pdf",
          "media_type": "application/pdf",
          "size_bytes": 48213,
          "text": "Q2 revenue grew 14% quarter over quarter..."
        }
      ]
    }
  ],
  "metadata": {}
}



Blocos de conteúdo

Cada entrada em messages tem um role de user ou assistant (resultados de ferramentas aparecem sob o role user, correspondendo ao modelo de conteúdo da Messages API pública) e um array content de blocos discriminados por type:

Um bloco cujo type você não reconhece é uma adição compatível com versões futuras. O único campo que ele garante é type; sua política pode inspecionar quaisquer outros campos presentes, mas não deve rejeitar a requisição por causa de um tipo não reconhecido.



O que a transcrição contém

A transcrição é a conversa como o usuário final a vê, até o ponto da inferência: texto da transcrição, chamadas de ferramentas e seus resultados, texto extraído de anexos e turnos anteriores. Ela nunca inclui prompts do sistema, definições de ferramentas, contexto interno da Anthropic, o raciocínio oculto do Claude ou bytes brutos de arquivos.

Um turno cujos blocos são todos excluídos é omitido inteiramente, então não presuma alternância estrita entre user e assistant.

As transcrições são enviadas sem truncamento, então uma conversa longa com anexos grandes produz um corpo de requisição grande, até um limite superior de 10 MB. Aumente o limite de corpo do seu servidor para aceitar esse teto. Vários padrões comuns são muito menores, incluindo client_max_body_size do nginx em 1 MB e express.json() do Express em 100 kB, e um corpo rejeitado conta como uma falha de webhook, então sob o tratamento de falha Allow the request, um prompt de tamanho excessivo chegaria ao modelo sem inspeção.



Valores de source

source.application é uma string aberta, não um enum fechado. Os valores conhecidos são claude-ai e claude-code; testes de conexão usam config-test. Novos valores podem aparecer, e seu servidor não deve rejeitar uma requisição por causa de um valor que não reconhece.

Trate source.application como metadados de roteamento informativos, não como um limite de confiança: não baseie uma decisão de política crítica de segurança apenas nele.



Retornar um veredito

Responda com HTTP 200 e um corpo JSON de veredito para ambos os resultados; o campo action discrimina. Para permitir a requisição:

{
  "action": "allow"
}

Para negá-la:

{
  "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"
}

Uma negação nunca é descartada por um problema de formatação: um deny_reason de tamanho excessivo é truncado, um reference_id malformado é descartado silenciosamente, e o action ainda é honrado.

O inverso não se aplica. Qualquer coisa diferente de HTTP 200 com um veredito analisável é uma falha de webhook, e o tratamento de falha da sua organização se aplica em vez de um veredito. Em particular:

• Não sinalize uma negação com um status de erro. Uma resposta não-200 é uma falha, não uma negação.
• Qualquer valor de action diferente de allow ou deny é tratado como uma falha de webhook.

A Anthropic lê no máximo 64 KiB do corpo da resposta, e o corpo deve estar descompactado. Redirecionamentos não são seguidos, e cookies são ignorados. Campos desconhecidos no corpo do veredito são ignorados, então você pode retornar um objeto mais rico junto com os campos documentados aqui.



Verificar a assinatura

As requisições são assinadas conforme a especificação Standard Webhooks, usando três cabeçalhos. A Anthropic envia os nomes dos cabeçalhos em minúsculas, e proxies são livres para alterar a capitalização, então consulte-os sem diferenciar maiúsculas de minúsculas.

Dois detalhes causam a maioria dos bugs de verificação:

• Verifique bytes brutos. Calcule o HMAC sobre o corpo exatamente como recebido, antes de qualquer análise ou recodificação de JSON.
• Decodifique o segredo com um decodificador base64 padrão. O segredo de assinatura é o valor após o prefixo whsec_, codificado com o alfabeto base64 padrão (+ e /), assim como a assinatura no cabeçalho. Um decodificador URL-safe deriva os bytes de chave errados sempre que o segredo contém + ou /, o que acontece na maioria das vezes.

Uma vez que sua organização tenha um segredo de assinatura, toda requisição que a Anthropic envia é assinada, e habilitar Inference hooks requer um, então rejeite qualquer requisição que chegue não assinada. Uma exceção: um teste de conexão enviado antes do primeiro salvamento da sua organização chega não assinado, porque o segredo de assinatura ainda não existe. Aceite requisições não assinadas até que seu administrador confirme que o segredo existe, depois rejeite-as.

Rotacionar o segredo é uma troca imediata, mas requisições assinadas com o segredo anterior ainda podem chegar por cerca de um minuto depois, além de qualquer coisa já em trânsito. Faça seu servidor de segurança de IA aceitar assinaturas de ambos os segredos durante a transição para que essas requisições atrasadas não sejam rejeitadas.

Os exemplos a seguir são implementações de servidor, então não há aba de shell: um servidor de segurança de IA é um serviço HTTPS de longa duração em vez de uma requisição única. Cada exemplo usa apenas a biblioteca padrão da linguagem; o projeto Standard Webhooks também publica bibliotecas de verificação para a maioria das linguagens.

import base64
import hashlib
import hmac
import time

TOLERANCE_SECONDS = 300


def verify(secret: str, headers: dict[str, str], body: bytes) -> bool:
    """Return True if the body was signed by Anthropic for this organization.

    Anthropic sends header names in lowercase, but proxies are free to
    re-case them, so normalize the lookup to lowercase.
    """
    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  # unsigned request: not from Anthropic

    try:
        signed_at = int(timestamp)
    except ValueError:
        return False
    if abs(time.time() - signed_at) > TOLERANCE_SECONDS:
        return False  # replayed, or the clocks disagree

    try:
        key = base64.b64decode(secret.removeprefix("whsec_"), validate=True)
    except ValueError:
        return False  # misconfigured secret: reject rather than crash

    payload = f"{message_id}.{timestamp}.".encode() + body
    expected = b"v1," + base64.b64encode(
        hmac.new(key, payload, hashlib.sha256).digest()
    )

    # Compara bytes: compare_digest em str gera erro com entrada não ASCII.
    return any(
        hmac.compare_digest(expected, candidate.encode())
        for candidate in signatures.split()
    )



Semântica operacional



Tempo limite e nova tentativa

Seu administrador define um tempo limite de veredito entre 1 e 10.000 ms (5.000 ms por padrão). O orçamento cobre toda a troca: conexão, handshake TLS, requisição e resposta.

A Anthropic tenta novamente exatamente uma vez, após um atraso de 100 ms, e apenas quando a tentativa de conexão falha. A nova tentativa compartilha o mesmo orçamento de tempo limite e carrega o mesmo webhook-id e a mesma assinatura. Uma vez que seu servidor de segurança de IA tenha respondido, a troca nunca é repetida.



Falhas de webhook

Tempos limite, status não-200 (redirecionamentos incluídos), corpos de resposta não analisáveis ou de tamanho excessivo e endpoints inacessíveis são todos falhas de webhook. Uma falha de webhook nunca se torna uma negação; em vez disso, a configuração de tratamento de falha da sua organização decide se a requisição afetada é bloqueada ou prossegue sem inspeção.



Circuit breaker

Falhas de webhook sustentadas atribuíveis ao seu servidor de segurança de IA acionam um "circuit breaker" (disjuntor) que interrompe a aplicação da política: a Anthropic para de contatar seu servidor, e o tratamento de falha se aplica a todas as requisições. A recuperação acontece do lado do administrador: corrija o servidor e, em seguida, peça ao seu administrador para reativar Enforce verdicts. Consulte Circuit breaker.



Latência

A aplicação da política adiciona o tempo de ida e volta do seu servidor de segurança de IA à "latency" (latência) de cada requisição governada na sua organização. Mantenha o veredito rápido e faça testes de carga no seu servidor antes de implantá-lo em uma organização grande.



Endereços IP de origem

As requisições para seu servidor de segurança de IA originam-se de 160.79.106.0/24, parte dos intervalos de IP de saída publicados pela Anthropic. Coloque esse bloco na lista de permissões, não os intervalos de entrada na mesma página, que não o cobrem. Colocar na lista de permissões reduz a exposição do seu servidor, mas não substitui a verificação de assinatura: o bloco carrega tráfego de saída da Anthropic além dos Inference hooks.



Compatibilidade futura

O protocolo cresce sem quebrar servidores escritos corretamente. Seu servidor deve ignorar:

• Campos de nível superior desconhecidos no prompt frame.
• Chaves desconhecidas em metadata.
• Novos valores de source.application.
• Novos valores de actor.type. actor é uma união discriminada por type, e "user" é o único tipo enviado atualmente; um tipo futuro garante apenas que type está presente.
• Blocos de conteúdo com um type não reconhecido.

Nunca rejeite uma requisição por causa de um tipo de bloco ou campo não reconhecido; leia os campos que você conhece e ignore o resto.

Outros tipos de evento de hook serão introduzidos no futuro. Um novo tipo de evento é uma adição que seu servidor não pode tratar ignorando um campo: a requisição ainda precisa de um veredito. Quando o type de nível superior for um valor que você não reconhece, retorne um veredito de permissão em vez de um status de erro; uma resposta de erro é uma falha de webhook, e falhas sustentadas acionam o circuit breaker.



Projete sua integração

Um servidor de segurança de IA de produção faz algumas escolhas de design além do protocolo de comunicação.

Deduplique com base em webhook-id. O cabeçalho webhook-id é único por entrega e igual ao request_id do corpo, e uma nova tentativa por falha de conexão o reutiliza, então ele funciona como uma chave de idempotência. Se você registrar vereditos, use-o como chave dos registros.

Registre vereditos e correlacione negações. Armazene cada veredito que você retorna junto com seu reference_id. Toda negação é registrada como uma atividade de conformidade inference_hooks_request_denied carregando o reference_id que seu servidor retornou, então você pode correlacionar negações no Activity Feed com os registros correspondentes no seu próprio sistema.

Arquive com um servidor que sempre permite. Para capturar transcrições em tempo real sem policiá-las, retorne {"action": "allow"} incondicionalmente e persista o frame após responder. Esta é uma alternativa baseada em push à consulta periódica da Compliance API, e responder antes de persistir mantém seu tempo de ida e volta fora do caminho crítico do usuário.

Escreva deny_reason para o usuário final. O texto que você retorna é o que o usuário vê quando sua requisição é bloqueada, truncado em 500 caracteres. Diga a ele o que mudar, como qual tipo de conteúdo remover, em vez de emitir um código de scanner que apenas sua equipe pode interpretar.



Próximos passos