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 avec 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é à 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 de webhooks.



Vérifier la signature

Chaque livraison comporte un en-tête X-Webhook-Signature. Utilisez l'assistant unwrap() du SDK pour vérifier la signature et analyser l'événement en une seule étape. Il 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.

from flask import Flask, request
import anthropic

client = anthropic.Anthropic()  # reads ANTHROPIC_WEBHOOK_SIGNING_KEY from env
app = Flask(__name__)


@app.route("/webhook", methods=["POST"])
def webhook():
    try:
        # unwrap() lève une exception si la signature est invalide ou si la charge utile est périmée
        event = client.beta.webhooks.unwrap(
            request.get_data(as_text=True),
            headers=dict(request.headers),
        )
    except Exception:
        return "invalid signature", 400

    if event.data.type == "session.status_idled":
        print("session idled:", event.data.id)
    # gérer les autres types d'événements

    return "", 200



Gérer un événement

Analysez le corps, effectuez un branchement sur data.type et 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, incluant 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-..."
  }
}

if event.data.type == "session.status_idled":
    session = client.beta.sessions.retrieve(event.data.id)
    notify_user(session)
return "", 204

L'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. La nouvelle tentative 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 échouées consécutives, 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.