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 Claude 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é.
• 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 webhook.



Vérifier la signature

Chaque livraison comporte les en-têtes webhook-id, webhook-timestamp et 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 5 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



Traiter 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. Toute autre réponse est comptabilisée contre le point de terminaison : un 3xx le désactive immédiatement (les redirections ne sont jamais suivies), tandis que les autres échecs font l'objet de nouvelles tentatives ; consultez Comportement de livraison pour les règles de nouvelle tentative et de désactivation automatique.

Chaque charge utile d'événement a la même structure, incluant le type d'événement, l'identifiant et l'horodatage du moment où l'événement s'est produit.

{
  "type": "event",
  "id": "whe_9d5c1f7e...",
  "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

Le 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

• Doublons : Un point de terminaison peut recevoir le même événement plusieurs fois, et chaque tentative livre le même event.id de niveau supérieur (la même valeur que l'en-tête webhook-id). Dédupliquez sur cette base.

• Portée de l'abonnement : Un événement n'est livré qu'aux points de terminaison abonnés à son type au moment où il est émis. Un événement émis alors qu'aucun point de terminaison n'est abonné à son type n'est jamais livré, et s'abonner ultérieurement ne le rattrape pas rétroactivement ; abonnez-vous donc à un type d'événement avant d'en avoir besoin.

• L'ordre n'est pas garanti. Les événements ne sont pas livrés dans l'ordre où ils se sont produits : session.status_idled peut arriver avant session.outcome_evaluation_ended même si le résultat a été produit en premier, et un événement .deleted peut arriver avant l'événement .archived pour la même ressource. Basez votre état sur la ressource que vous récupérez, et non sur l'ordre d'arrivée des événements.

• Nouvelles tentatives : Pour chaque point de terminaison et chaque événement, Anthropic effectue jusqu'à trois tentatives de livraison (une réponse qui déclenche la désactivation automatique, décrite plus loin dans cette section, ne fait jamais l'objet d'une nouvelle tentative) avec un délai exponentiel aléatoire compris entre 5 et 120 secondes. Chaque tentative livre le même event.id. Après l'échec de la dernière tentative, l'événement est abandonné : il n'est pas mis en file d'attente pour une livraison ultérieure et aucun signal n'indique qu'il a été perdu. Les webhooks ne constituent pas un journal durable ; si vous devez observer chaque transition, effectuez une réconciliation en listant ou en récupérant la ressource via l'API.

• Horodatages : L'en-tête webhook-timestamp est apposé au moment où une tentative de livraison est signée et est régénéré à chaque nouvelle tentative, de sorte que les nouvelles tentatives ne sont pas rejetées par la vérification de fraîcheur du SDK. Il s'agit de l'horloge de la tentative de livraison, et non de celle de l'événement : utilisez le champ created_at de la charge utile de l'événement pour savoir quand l'événement s'est produit.

• Désactivation automatique : Un point de terminaison est automatiquement défini sur disabled avec un disabled_reason lisible par machine dans trois cas :

  • Le point de terminaison renvoie une réponse 3xx. Les redirections ne sont jamais suivies ; cela désactive le point de terminaison immédiatement, dès la première tentative, avec la raison auto-disabled: endpoint URL returned a redirect (3xx). Si votre point de terminaison change d'adresse, mettez à jour l'URL dans la Console et réactivez le point de terminaison.
  • L'URL du point de terminaison se résout en une adresse IP non publique lorsque Anthropic se connecte. Cela désactive le point de terminaison immédiatement, avec la raison auto-disabled: endpoint URL resolved to an invalid address.
  • Les livraisons vers le point de terminaison échouent de manière continue pendant une période prolongée, avec la raison auto-disabled after sustained delivery failures. Le déclencheur est la durée pendant laquelle le point de terminaison a échoué sans interruption, et non un nombre de livraisons. Un seul 2xx réinitialise la fenêtre, de sorte qu'un événement isolé instable ne peut pas désactiver le point de terminaison.

  Ces trois cas sont réversibles : réactivez le point de terminaison dans la Console après avoir résolu le problème. Les événements émis pendant que le point de terminaison était désactivé ne sont pas rejoués.