S'abonner aux webhooks

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

Les événements de webhook renvoient le type et l'id de l'événement, et non l'objet complet. Lorsque vous recevez un événement de 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 maintient chaque livraison de petite taille.

Types d'événements pris en charge

Enregistrer un point de terminaison

Visitez Manage > Webhooks dans la Claude Console.

Un point de terminaison de webhook se compose de :

• URL : Doit être en HTTPS sur le port 443 avec un nom d'hôte résoluble 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é lors de la création. Il n'est affiché qu'une seule fois, alors stockez-le de manière sécurisée pour vérifier les livraisons de webhook.

Vérifier la signature

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

Définissez ANTHROPIC_WEBHOOK_SIGNING_KEY sur 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 obsolète
        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 ID. Renvoyez n'importe quel 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, comprenant 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

L'event.id de premier niveau 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 plus d'une fois, et chaque tentative livre le même event.id de premier niveau (la même valeur que l'en-tête webhook-id). Dédupliquez sur celui-ci.

• 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 plus tard ne le rattrape pas, alors abonnez-vous à 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. Pilotez votre état à partir de la ressource que vous récupérez, et non à partir de l'ordre dans lequel les événements arrivent.

• Nouvelles tentatives : Pour chaque point de terminaison et é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 backoff exponentiel avec gigue 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 il n'y a aucun signal indiquant qu'il a été perdu. Les webhooks ne sont pas un journal durable, donc si vous devez observer chaque transition, réconciliez en listant ou en récupérant la ressource via l'API.

• Horodatages : L'en-tête webhook-timestamp est estampillé lorsqu'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. C'est l'horloge de la tentative de livraison, et non de l'événement : utilisez le 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'emplacement, 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 lorsqu'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 continuellement 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 seul événement instable ne peut pas désactiver le point de terminaison.

  Les trois 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.