S'abonner aux webhooks

Les sessions sont des interactions de longue durée. Alors que la plupart des interactions en temps réel passent par le flux d'événements SSE, les webhooks vous notifient des changements d'état majeurs.

Les événements webhook renvoient le type et l'id de l'événement, et non l'objet complet. Lorsque vous recevez un événement webhook, vous devez récupérer l'objet directement via un appel GET. Cela évite de livrer des données obsolètes lors des nouvelles tentatives et garantit que chaque livraison reste légère.



Types d'événements pris en charge



Enregistrer un point de terminaison

Rendez-vous dans Manage > Webhooks dans la Console.

Un point de terminaison webhook se compose de :

• URL : Doit être en HTTPS sur le port 443 avec un nom d'hôte résolvable publiquement.
• Types d'événements : La liste des valeurs data.type que ce point de terminaison reçoit. Un point de terminaison ne reçoit que les événements auxquels il est abonné, ainsi que les événements de test (voir Comportement de livraison).
• Secret de signature : Un secret de 32 octets préfixé par whsec_, généré lors de la création. Il n'est affiché qu'une seule fois, stockez-le donc de manière sécurisée pour vérifier les livraisons webhook.



Vérifier la signature

Chaque livraison comporte un en-tête X-Webhook-Signature. Utilisez la fonction d'aide unwrap() du SDK pour vérifier la signature et analyser l'événement en une seule étape. Elle lève une exception si la signature est invalide ou si la charge utile date de plus de cinq minutes.

Définissez ANTHROPIC_WEBHOOK_SIGNING_KEY avec le secret préfixé par whsec_ affiché lors de la création du point de terminaison.



Traiter un événement

Analysez le corps, effectuez un branchement sur data.type, puis récupérez la ressource par son ID. Renvoyez n'importe quel code 2xx pour accuser réception. Tout autre code (y compris 3xx) est considéré comme un échec et déclenche une nouvelle tentative.

Chaque charge utile d'événement a la même structure, comprenant le type d'événement, l'identifiant et l'horodatage de création de l'objet.

{
  "type": "event",
  "id": "event_01ABC...",
  "created_at": "2026-03-18T14:05:22Z",
  "data": {
    "type": "session.status_idled",
    "id": "sesn_01XYZ...",
    "organization_id": "8a3d2f1e-...",
    "workspace_id": "c7b0e4d9-..."
  }
}

Le champ event.id de niveau supérieur est unique par événement, et non par livraison. Si vous recevez le même event.id deux fois, il s'agit d'une nouvelle tentative et vous pouvez l'ignorer.



Comportement de livraison

• L'ordre n'est pas garanti. session.status_idled peut arriver avant session.outcome_evaluation_ended même si le résultat a été produit en premier. Utilisez l'horodatage created_at pour trier si l'ordre est important.
• Nouvelles tentatives : Anthropic effectue au moins une nouvelle tentative. Celle-ci livre le même event.id.
• Les redirections ne sont pas suivies. Un code 3xx est traité comme un échec. Si votre point de terminaison change d'adresse, mettez à jour l'URL dans la Console.
• Désactivation automatique : Un point de terminaison est automatiquement défini sur disabled avec un disabled_reason lisible par machine après environ 20 livraisons consécutives échouées, ou immédiatement si le nom d'hôte se résout en une adresse IP privée ou si le point de terminaison renvoie une redirection. Réactivez-le manuellement dans la Console après avoir résolu le problème.