Sviluppare un'integrazione Inference hooks

Un'integrazione Inference hooks è un server di sicurezza IA: un servizio HTTPS che Anthropic chiama. Per ogni richiesta governata, il tuo server riceve una POST firmata contenente la trascrizione della conversazione e risponde con un verdetto di autorizzazione o rifiuto. Questa pagina documenta il protocollo per costruire quel server: gli schemi di richiesta e verdetto, la verifica della firma e il contratto operativo.

Per attivare gli Inference hooks e puntarli al tuo endpoint, consulta Configurare gli Inference hooks. Per sapere cosa sono gli Inference hooks e quando usarli, consulta la panoramica degli Inference hooks.



Ottenere un primo round trip di verdetto

L'integrazione funzionante più piccola è un server che legge ogni richiesta e la autorizza. Esegui uno dei seguenti server, esponilo a un URL https:// pubblico (ad esempio, dietro un reverse proxy con terminazione TLS o un tunnel), quindi chiedi al tuo amministratore di impostarlo come endpoint e testare la connessione: il risultato di Test connection riporta il verdetto di autorizzazione restituito dal tuo server.

# Esegui con: 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):
        # Svuota il body; le trascrizioni possono essere di megabyte.
        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()



Ricevere una richiesta

Anthropic invia una POST HTTPS all'URL configurato dal tuo amministratore. L'intero URL configurato è l'endpoint: non esiste un suffisso di percorso fisso, quindi scegli qualsiasi percorso adatto al tuo server.

Ospita il tuo server di sicurezza IA dove Anthropic può raggiungerlo: un URL https:// sulla porta 443, su un host instradabile pubblicamente (gli intervalli privati, di loopback e carrier-grade NAT vengono rifiutati al momento della connessione), con un certificato che si convalida rispetto al trust store delle CA pubbliche, che risponde senza redirect. L'URL configurato deve essere la destinazione finale. Configurare gli Inference hooks spiega come il tuo amministratore imposta e testa l'URL.

Ogni richiesta contiene questi header fissi, insieme a eventuali header di richiesta personalizzati configurati dal tuo amministratore e, una volta che la tua organizzazione dispone di un segreto di firma, gli header di firma webhook-* descritti in Verificare la firma:

Oggi esiste un solo evento hook: il prompt frame, inviato una volta per ogni richiesta di inferenza governata, prima che l'inferenza inizi. Anthropic trattiene la richiesta finché il tuo server di sicurezza IA non risponde o scade il timeout del verdetto.



Il prompt frame

Il corpo della richiesta è un oggetto JSON con questi campi:

Un esempio di corpo della richiesta:

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



Blocchi di contenuto

Ogni voce in messages ha un role di user o assistant (i risultati degli strumenti appaiono sotto il ruolo user, in linea con il modello di contenuto della Messages API pubblica) e un array content di blocchi discriminati da type:

Un blocco il cui type non riconosci è un'aggiunta compatibile con le versioni future. L'unico campo che garantisce è type; la tua policy può ispezionare qualsiasi altro campo presente, ma non deve rifiutare la richiesta a causa di un tipo non riconosciuto.



Cosa contiene la trascrizione

La trascrizione è la conversazione così come la vede l'utente finale, fino al punto dell'inferenza: testo della trascrizione, chiamate agli strumenti e relativi risultati, testo estratto dagli allegati e turni precedenti. Non include mai prompt di sistema, definizioni degli strumenti, contesto interno di Anthropic, il ragionamento nascosto di Claude o byte grezzi dei file.

Un turno in cui ogni blocco è escluso viene omesso interamente, quindi non presumere una rigida alternanza tra user e assistant.

Le trascrizioni vengono inviate senza troncamento, quindi una conversazione lunga con allegati di grandi dimensioni produce un corpo di richiesta grande, fino a un limite superiore di 10 MB. Aumenta il limite del corpo del tuo server per accettare quel tetto. Diversi valori predefiniti comuni sono molto più piccoli, tra cui client_max_body_size di nginx a 1 MB ed express.json() di Express a 100 kB, e un corpo rifiutato conta come un errore del webhook, quindi con la gestione degli errori Allow the request un prompt sovradimensionato raggiungerebbe il modello senza essere ispezionato.



Valori di source

source.application è una stringa aperta, non un enum chiuso. I valori noti sono claude-ai e claude-code; i test di connessione usano config-test. Nuovi valori potrebbero apparire e il tuo server non deve rifiutare una richiesta a causa di un valore che non riconosce.

Tratta source.application come metadati di routing informativi, non come un confine di fiducia: non basare una decisione di policy critica per la sicurezza solo su di esso.



Restituire un verdetto

Rispondi con HTTP 200 e un corpo JSON di verdetto per entrambi gli esiti; il campo action discrimina. Per autorizzare la richiesta:

{
  "action": "allow"
}

Per rifiutarla:

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

Un rifiuto non viene mai scartato per un problema di formattazione: un deny_reason sovradimensionato viene troncato, un reference_id malformato viene silenziosamente eliminato e l'action viene comunque rispettata.

Il contrario non vale. Qualsiasi cosa diversa da HTTP 200 con un verdetto analizzabile è un errore del webhook, e si applica la gestione degli errori della tua organizzazione invece di un verdetto. In particolare:

• Non segnalare un rifiuto con uno stato di errore. Una risposta non-200 è un errore, non un rifiuto.
• Qualsiasi valore di action diverso da allow o deny viene trattato come un errore del webhook.

Anthropic legge al massimo 64 KiB del corpo della risposta, e il corpo deve essere non compresso. I redirect non vengono seguiti e i cookie vengono ignorati. I campi sconosciuti nel corpo del verdetto vengono ignorati, quindi puoi restituire un oggetto più ricco insieme ai campi documentati qui.



Verificare la firma

Le richieste sono firmate secondo la specifica Standard Webhooks, utilizzando tre header. Anthropic invia i nomi degli header in minuscolo, e i proxy sono liberi di modificarne la capitalizzazione, quindi cercali in modo case-insensitive.

Due dettagli causano la maggior parte dei bug di verifica:

• Verifica i byte grezzi. Calcola l'HMAC sul corpo esattamente come ricevuto, prima di qualsiasi parsing o ricodifica JSON.
• Decodifica il segreto con un decoder base64 standard. Il segreto di firma è il valore dopo il prefisso whsec_, codificato con l'alfabeto base64 standard (+ e /), così come la firma nell'header. Un decoder URL-safe deriva i byte della chiave errati ogni volta che il segreto contiene + o /, il che accade nella maggior parte dei casi.

Una volta che la tua organizzazione dispone di un segreto di firma, ogni richiesta inviata da Anthropic è firmata, e abilitare gli Inference hooks ne richiede uno, quindi rifiuta qualsiasi richiesta che arrivi non firmata. Un'eccezione: un test di connessione inviato prima del primo salvataggio della tua organizzazione arriva non firmato, perché il segreto di firma non esiste ancora. Accetta richieste non firmate finché il tuo amministratore non conferma che il segreto esiste, poi rifiutale.

La rotazione del segreto è un passaggio immediato, ma le richieste firmate con il segreto precedente possono ancora arrivare per circa un minuto dopo, più qualsiasi cosa già in transito. Fai in modo che il tuo server di sicurezza IA accetti firme da entrambi i segreti durante il passaggio, così che quelle richieste ritardatarie non vengano rifiutate.

I seguenti esempi sono implementazioni server, quindi non c'è una scheda shell: un server di sicurezza IA è un servizio HTTPS a lunga esecuzione piuttosto che una richiesta singola. Ogni esempio usa solo la libreria standard del linguaggio; il progetto Standard Webhooks pubblica anche librerie di verifica per la maggior parte dei linguaggi.

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()
    )

    # Confronta i byte: compare_digest su str genera un errore con input non-ASCII.
    return any(
        hmac.compare_digest(expected, candidate.encode())
        for candidate in signatures.split()
    )



Semantica operativa



Timeout e retry

Il tuo amministratore imposta un timeout del verdetto tra 1 e 10.000 ms (5.000 ms per impostazione predefinita). Il budget copre l'intero scambio: connessione, handshake TLS, richiesta e risposta.

Anthropic riprova esattamente una volta, dopo un ritardo di 100 ms, e solo quando il tentativo di connessione fallisce. Il retry condivide lo stesso budget di timeout e porta lo stesso webhook-id e la stessa firma. Una volta che il tuo server di sicurezza IA ha risposto, lo scambio non viene mai ritentato.



Errori del webhook

Timeout, stati non-200 (redirect inclusi), corpi di risposta non analizzabili o sovradimensionati ed endpoint irraggiungibili sono tutti errori del webhook. Un errore del webhook non diventa mai un rifiuto; invece, l'impostazione di gestione degli errori della tua organizzazione decide se la richiesta interessata viene bloccata o procede senza ispezione.



Circuit breaker

Errori del webhook prolungati attribuibili al tuo server di sicurezza IA fanno scattare un "circuit breaker" (interruttore automatico) che interrompe l'enforcement: Anthropic smette di contattare il tuo server e la gestione degli errori si applica a ogni richiesta. Il ripristino avviene lato amministratore: correggi il server, quindi chiedi al tuo amministratore di riattivare Enforce verdicts. Vedi Circuit breaker.



Latenza

L'enforcement aggiunge il round trip del tuo server di sicurezza IA alla "latency" (latenza) di ogni richiesta governata nella tua organizzazione. Mantieni il verdetto veloce ed esegui test di carico sul tuo server prima di distribuirlo a una grande organizzazione.



Indirizzi IP di origine

Le richieste al tuo server di sicurezza IA provengono da 160.79.106.0/24, parte degli intervalli IP in uscita pubblicati da Anthropic. Inserisci in allowlist quel blocco, non gli intervalli in entrata sulla stessa pagina, che non lo coprono. L'allowlisting restringe l'esposizione del tuo server, ma non sostituisce la verifica della firma: il blocco trasporta traffico in uscita di Anthropic oltre agli Inference hooks.



Compatibilità futura

Il protocollo cresce senza rompere i server scritti correttamente. Il tuo server deve ignorare:

• Campi di primo livello sconosciuti nel prompt frame.
• Chiavi sconosciute in metadata.
• Nuovi valori di source.application.
• Nuovi valori di actor.type. actor è un'unione discriminata su type, e "user" è l'unico tipo inviato oggi; un tipo futuro garantisce solo che type sia presente.
• Blocchi di contenuto con un type non riconosciuto.

Non rifiutare mai una richiesta a causa di un tipo di blocco o campo non riconosciuto; leggi i campi che conosci e salta il resto.

Altri tipi di evento hook saranno introdotti in futuro. Un nuovo tipo di evento è un'aggiunta che il tuo server non può gestire saltando un campo: la richiesta necessita comunque di un verdetto. Quando il type di primo livello è un valore che non riconosci, restituisci un verdetto di autorizzazione piuttosto che uno stato di errore; una risposta di errore è un errore del webhook, ed errori prolungati fanno scattare il circuit breaker.



Progettare la tua integrazione

Un server di sicurezza IA di produzione fa alcune scelte di progettazione oltre al protocollo di rete.

Deduplica su webhook-id. L'header webhook-id è univoco per consegna ed è uguale al request_id del corpo, e un retry per errore di connessione lo riutilizza, quindi funziona come chiave di idempotenza. Se registri i verdetti, usa questo come chiave dei record.

Registra i verdetti e collega i rifiuti. Memorizza ogni verdetto che restituisci insieme al suo reference_id. Ogni rifiuto viene registrato come attività di conformità inference_hooks_request_denied che contiene il reference_id restituito dal tuo server, così puoi collegare i rifiuti nell'Activity Feed ai record corrispondenti nel tuo sistema.

Archivia con un server always-allow. Per catturare le trascrizioni in tempo reale senza controllarle, restituisci {"action": "allow"} incondizionatamente e persisti il frame dopo aver risposto. Questa è un'alternativa push-based al polling della Compliance API, e rispondere prima di persistere mantiene il tuo round trip fuori dal percorso critico dell'utente.

Scrivi deny_reason per l'utente finale. Il testo che restituisci è ciò che l'utente vede quando la sua richiesta viene bloccata, troncato a 500 caratteri. Digli cosa cambiare, ad esempio quale tipo di contenuto rimuovere, piuttosto che emettere un codice di scanner che solo il tuo team può interpretare.



Passaggi successivi