Développer une intégration Inference hooks

Une intégration Inference hooks est un serveur de sécurité IA : un service HTTPS qu'Anthropic appelle. Pour chaque requête gouvernée, votre serveur reçoit un POST signé contenant la transcription de la conversation et répond avec un verdict d'autorisation ou de refus. Cette page documente le protocole pour construire ce serveur : les schémas de requête et de verdict, la vérification de signature et le contrat opérationnel.

Pour activer les Inference hooks et les pointer vers votre point de terminaison, consultez Configurer les Inference hooks. Pour savoir ce que sont les Inference hooks et quand les utiliser, consultez la présentation des Inference hooks.



Obtenir un premier aller-retour de verdict

L'intégration fonctionnelle la plus simple est un serveur qui lit chaque requête et l'autorise. Exécutez l'un des serveurs suivants, exposez-le à une URL publique https:// (par exemple, derrière un proxy inverse terminant TLS ou un tunnel), puis demandez à votre administrateur de le définir comme point de terminaison et de tester la connexion : le résultat de Test connection indique le verdict d'autorisation que votre serveur a renvoyé.

# Exécutez avec : 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):
        # Videz le corps ; les transcriptions peuvent atteindre plusieurs mégaoctets.
        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()



Recevoir une requête

Anthropic envoie un POST HTTPS à l'URL que votre administrateur configure. L'URL configurée entière constitue le point de terminaison : il n'y a pas de suffixe de chemin fixe, vous pouvez donc choisir n'importe quel chemin qui convient à votre serveur.

Hébergez votre serveur de sécurité IA là où Anthropic peut l'atteindre : une URL https:// sur le port 443, sur un hôte routable publiquement (les plages privées, de bouclage et de NAT de classe opérateur sont refusées au moment de la connexion), avec un certificat validé par le magasin de confiance des autorités de certification publiques, répondant sans redirections. L'URL configurée doit être la destination finale. Configurer les Inference hooks explique comment votre administrateur définit et teste l'URL.

Chaque requête comporte ces en-têtes fixes, ainsi que tous les en-têtes de requête personnalisés que votre administrateur a configurés et, une fois que votre organisation dispose d'un secret de signature, les en-têtes de signature webhook-* décrits dans Vérifier la signature :

Il existe aujourd'hui un seul événement de hook : le « prompt frame » (trame de prompt), envoyé une fois par requête d'inférence gouvernée, avant le début de l'inférence. Anthropic retient la requête jusqu'à ce que votre serveur de sécurité IA réponde ou que le délai d'attente du verdict expire.



La trame de prompt

Le corps de la requête est un objet JSON avec les champs suivants :

Un exemple de corps de requête :

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



Blocs de contenu

Chaque entrée dans messages a un role de user ou assistant (les résultats d'outils apparaissent sous le rôle user, conformément au modèle de contenu de l'API Messages publique) et un tableau content de blocs discriminés par type :

Un bloc dont vous ne reconnaissez pas le type est un ajout compatible avec les versions futures. Le seul champ qu'il garantit est type ; votre politique peut inspecter tous les autres champs présents, mais ne doit pas rejeter la requête à cause d'un type non reconnu.



Ce que contient la transcription

La transcription est la conversation telle que l'utilisateur final la voit, jusqu'au point d'inférence : texte de la transcription, appels d'outils et leurs résultats, texte extrait des pièces jointes et tours précédents. Elle n'inclut jamais les invites système, les définitions d'outils, le contexte interne à Anthropic, le raisonnement caché de Claude ni les octets bruts des fichiers.

Un tour dont tous les blocs sont exclus est entièrement omis, donc ne supposez pas une alternance stricte entre utilisateur et assistant.

Les transcriptions sont envoyées sans troncature, donc une longue conversation avec de grandes pièces jointes produit un corps de requête volumineux, jusqu'à une limite supérieure de 10 Mo. Augmentez la limite de corps de votre serveur pour accepter ce plafond. Plusieurs valeurs par défaut courantes sont bien plus petites, notamment client_max_body_size de nginx à 1 Mo et express.json() d'Express à 100 ko, et un corps rejeté compte comme un échec de webhook, donc avec la gestion d'échec Allow the request, un prompt surdimensionné atteindrait le modèle sans inspection.



Valeurs de source

source.application est une chaîne ouverte, pas une énumération fermée. Les valeurs connues sont claude-ai et claude-code ; les tests de connexion utilisent config-test. De nouvelles valeurs peuvent apparaître, et votre serveur ne doit pas rejeter une requête à cause d'une valeur qu'il ne reconnaît pas.

Traitez source.application comme des métadonnées de routage indicatives, pas comme une frontière de confiance : ne fondez pas une décision de politique critique pour la sécurité uniquement sur cette valeur.



Renvoyer un verdict

Répondez avec HTTP 200 et un corps de verdict JSON pour les deux résultats ; le champ action discrimine. Pour autoriser la requête :

{
  "action": "allow"
}

Pour la refuser :

{
  "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 refus n'est jamais écarté à cause d'un problème de formatage : un deny_reason surdimensionné est tronqué, un reference_id mal formé est silencieusement supprimé, et l'action est toujours honorée.

L'inverse n'est pas vrai. Tout ce qui n'est pas HTTP 200 avec un verdict analysable est un échec de webhook, et la gestion des échecs de votre organisation s'applique à la place d'un verdict. En particulier :

• Ne signalez pas un refus avec un statut d'erreur. Une réponse non-200 est un échec, pas un refus.
• Toute valeur d'action autre que allow ou deny est traitée comme un échec de webhook.

Anthropic lit au plus 64 Kio du corps de la réponse, et le corps doit être non compressé. Les redirections ne sont pas suivies, et les cookies sont ignorés. Les champs inconnus dans le corps du verdict sont ignorés, vous pouvez donc renvoyer un objet plus riche en plus des champs documentés ici.



Vérifier la signature

Les requêtes sont signées selon la spécification Standard Webhooks, en utilisant trois en-têtes. Anthropic envoie les noms d'en-têtes en minuscules, et les proxys sont libres de modifier leur casse, donc recherchez-les de manière insensible à la casse.

Deux détails causent la plupart des bugs de vérification :

• Vérifiez les octets bruts. Calculez le HMAC sur le corps exactement tel que reçu, avant toute analyse ou ré-encodage JSON.
• Décodez le secret avec un décodeur base64 standard. Le secret de signature est la valeur après le préfixe whsec_, encodée avec l'alphabet base64 standard (+ et /), tout comme la signature dans l'en-tête. Un décodeur URL-safe dérive les mauvais octets de clé dès que le secret contient + ou /, ce qui est le cas la plupart du temps.

Une fois que votre organisation dispose d'un secret de signature, chaque requête qu'Anthropic envoie est signée, et l'activation des Inference hooks en nécessite un, donc rejetez toute requête qui arrive non signée. Une exception : un test de connexion envoyé avant le premier enregistrement de votre organisation arrive non signé, car le secret de signature n'existe pas encore. Acceptez les requêtes non signées jusqu'à ce que votre administrateur confirme que le secret existe, puis rejetez-les.

La rotation du secret est un basculement immédiat, mais des requêtes signées avec le secret précédent peuvent encore arriver pendant environ une minute après, plus tout ce qui est déjà en transit. Faites en sorte que votre serveur de sécurité IA accepte les signatures des deux secrets pendant le basculement afin que ces requêtes retardataires ne soient pas rejetées.

Les exemples suivants sont des implémentations de serveur, il n'y a donc pas d'onglet shell : un serveur de sécurité IA est un service HTTPS de longue durée plutôt qu'une requête ponctuelle. Chaque exemple utilise uniquement la bibliothèque standard du langage ; le projet Standard Webhooks publie également des bibliothèques de vérification pour la plupart des langages.

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

    # Comparer les octets : compare_digest sur str lève une erreur avec une entrée non-ASCII.
    return any(
        hmac.compare_digest(expected, candidate.encode())
        for candidate in signatures.split()
    )



Sémantique opérationnelle



Délai d'attente et nouvelle tentative

Votre administrateur définit un délai d'attente de verdict entre 1 et 10 000 ms (5 000 ms par défaut). Le budget couvre l'échange entier : connexion, négociation TLS, requête et réponse.

Anthropic réessaie exactement une fois, après un délai de 100 ms, et uniquement lorsque la tentative de connexion échoue. La nouvelle tentative partage le même budget de délai d'attente et porte le même webhook-id et la même signature. Une fois que votre serveur de sécurité IA a répondu, l'échange n'est jamais retenté.



Échecs de webhook

Les dépassements de délai, les statuts non-200 (redirections incluses), les corps de réponse non analysables ou surdimensionnés et les points de terminaison inaccessibles sont tous des échecs de webhook. Un échec de webhook ne devient jamais un refus ; à la place, le paramètre de gestion des échecs de votre organisation décide si la requête concernée est bloquée ou se poursuit sans inspection.



Disjoncteur

Des échecs de webhook soutenus attribuables à votre serveur de sécurité IA déclenchent un « circuit breaker » (disjoncteur) qui arrête l'application des verdicts : Anthropic cesse de contacter votre serveur, et la gestion des échecs s'applique à chaque requête. La récupération se fait côté administrateur : corrigez le serveur, puis demandez à votre administrateur de réactiver Enforce verdicts. Voir Disjoncteur.



Latence

L'application des verdicts ajoute l'aller-retour de votre serveur de sécurité IA à la « latency » (latence) de chaque requête gouvernée dans votre organisation. Gardez le verdict rapide, et effectuez des tests de charge sur votre serveur avant de le déployer dans une grande organisation.



Adresses IP sources

Les requêtes vers votre serveur de sécurité IA proviennent de 160.79.106.0/24, qui fait partie des plages IP sortantes publiées par Anthropic. Mettez ce bloc en liste d'autorisation, pas les plages entrantes de la même page, qui ne le couvrent pas. La mise en liste d'autorisation réduit l'exposition de votre serveur, mais ne remplace pas la vérification de signature : le bloc transporte du trafic sortant d'Anthropic au-delà des Inference hooks.



Compatibilité ascendante

Le protocole évolue sans casser les serveurs correctement écrits. Votre serveur doit ignorer :

• Les champs de niveau supérieur inconnus sur la trame de prompt.
• Les clés inconnues dans metadata.
• Les nouvelles valeurs de source.application.
• Les nouvelles valeurs de actor.type. actor est une union discriminée par type, et "user" est le seul type envoyé aujourd'hui ; un type futur garantit uniquement que type est présent.
• Les blocs de contenu avec un type non reconnu.

Ne rejetez jamais une requête à cause d'un type de bloc ou d'un champ non reconnu ; lisez les champs que vous connaissez et ignorez le reste.

D'autres types d'événements de hook seront introduits à l'avenir. Un nouveau type d'événement est un ajout que votre serveur ne peut pas gérer en ignorant un champ : la requête nécessite toujours un verdict. Lorsque le type de niveau supérieur est une valeur que vous ne reconnaissez pas, renvoyez un verdict d'autorisation plutôt qu'un statut d'erreur ; une réponse d'erreur est un échec de webhook, et des échecs soutenus déclenchent le disjoncteur.



Concevoir votre intégration

Un serveur de sécurité IA de production fait quelques choix de conception au-delà du protocole réseau.

Dédupliquez sur webhook-id. L'en-tête webhook-id est unique par livraison et égal au request_id du corps, et une nouvelle tentative après échec de connexion le réutilise, donc il fonctionne comme clé d'idempotence. Si vous enregistrez les verdicts, indexez les enregistrements sur cette clé.

Enregistrez les verdicts et joignez les refus. Stockez chaque verdict que vous renvoyez avec son reference_id. Chaque refus est enregistré comme une activité de conformité inference_hooks_request_denied portant le reference_id que votre serveur a renvoyé, vous pouvez donc joindre les refus dans le flux d'activité aux enregistrements correspondants dans votre propre système.

Archivez avec un serveur qui autorise toujours. Pour capturer les transcriptions en temps réel sans les contrôler, renvoyez {"action": "allow"} inconditionnellement et persistez la trame après avoir répondu. C'est une alternative basée sur le push à l'interrogation de l'API de conformité, et répondre avant de persister garde votre aller-retour hors du chemin critique de l'utilisateur.

Rédigez deny_reason pour l'utilisateur final. Le texte que vous renvoyez est ce que l'utilisateur voit lorsque sa requête est bloquée, tronqué à 500 caractères. Dites-lui ce qu'il doit changer, par exemple quel type de contenu supprimer, plutôt que d'émettre un code de scanner que seule votre équipe peut interpréter.



Prochaines étapes