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 » (rappels HTTP) 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 permet de garder chaque livraison légère.

Types d'événements pris en charge

Enregistrer un point de terminaison

Dans la Claude Console, accédez à la page Webhooks (platform.claude.com/settings/workspaces/default/webhooks). Chaque point de terminaison appartient à un espace de travail. Sélectionnez l'espace de travail souhaité dans le sélecteur d'espace de travail de la barre latérale.

Un « endpoint » (point de terminaison) de 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é 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 de webhook.

Vérifier la signature

Chaque livraison comporte 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 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 deux fois le même event.id, 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 niveau supérieur (la même valeur que l'en-tête webhook-id). Dédupliquez sur cette valeur.

• 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 un abonnement ultérieur ne le rattrape pas ; 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. Pilotez votre état à partir de la ressource que vous récupérez, et non de 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 « exponential backoff » (délai exponentiel) avec gigue 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 un rapprochement en listant ou en récupérant la ressource via l'API.

• Horodatages : L'en-tête webhook-timestamp est apposé 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. Il s'agit de l'horloge de la tentative de livraison, et non de l'événement : utilisez le champ created_at de la charge utile de l'événement pour connaître le moment où 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 s'y 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 échoue sans interruption, et non un nombre de livraisons. Un seul 2xx réinitialise la fenêtre, de sorte qu'un événement 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.