Webhooks d'organisation

Un « organization webhook endpoint » (point de terminaison de webhook d'organisation) reçoit un événement lorsqu'Anthropic restreint ou bannit l'un des profils utilisateur de votre organisation, et lorsque la restriction ou le bannissement prend fin. Vous le gérez avec l'Admin API sous /v1/organizations/webhooks.

Tout membre de votre organisation peut lister et consulter les points de terminaison de webhook d'organisation avec l'API, mais seuls les membres ayant le rôle admin, owner ou primary owner peuvent les créer, les modifier ou les supprimer, ou remplacer leur secret de signature.

Avant de commencer

Vous avez besoin des éléments suivants :

• Une organisation sur la Claude API pour laquelle les webhooks d'organisation sont activés et pour laquelle la préparation HIPAA n'est pas activée. Pour demander l'accès, contactez votre équipe de compte Anthropic.
• L'un de ces identifiants :
  • Une clé Admin API.
  • Un jeton porteur OAuth avec la portée org:admin.
  • Une clé personnelle ou de compte de service qui n'est pas limitée à un espace de travail.

Types d'événements

Les points de terminaison de webhook d'organisation acceptent deux types d'événements. Tous deux concernent des « enforcement actions » (mesures d'application) sur des profils utilisateur. Une mesure d'application est une restriction ou un bannissement qu'Anthropic impose au client final représenté par un profil.

La suppression d'un profil met fin à ses mesures ouvertes sans événement user_profile.enforcement_action_resolved.

Avant votre premier événement

Vos profils n'auront pas les champs enforcement_status et enforcement_actions tant que les mesures d'application ne seront pas activées pour votre organisation. D'ici là, ainsi que dans toute requête dont l'en-tête anthropic-beta contient user-profiles-2026-09-04 ou une valeur antérieure, les réponses omettent ces champs et le filtre de liste enforcement_status[] renvoie une erreur 400. Pour obtenir ces champs, retirez cette valeur de vos requêtes.

Si une mesure d'application a été ouverte avant qu'Anthropic n'active les mesures d'application et la livraison des événements pour votre organisation, ou avant que vous n'enregistriez votre point de terminaison, vous ne recevez pas d'événement user_profile.enforcement_action_opened pour celle-ci. La mesure apparaît tout de même sur le profil. Pour trouver ces mesures, listez vos profils avec enforcement_status[]=restricted et enforcement_status[]=banned. Une réponse peut renvoyer moins de profils que limit, voire aucun, avant la fin de la liste ; continuez donc à demander des pages jusqu'à ce que next_page soit null.

Contenu d'un événement

Les événements contiennent des ID, et non la mesure ou le profil. data.id est l'ID du profil, et data.enforcement_action_id est l'ID de la mesure, qui commence par enac_ :

{
  "type": "event",
  "id": "whe_4f2a9c1e7b3d5a8f0e6c2b9d1a7f3e5c",
  "created_at": "2026-10-15T17:02:41Z",
  "data": {
    "type": "user_profile.enforcement_action_opened",
    "id": "uprof_011CZkZCu8hGbp5mYRQgUmz9",
    "enforcement_action_id": "enac_011CZkZEq4TnWb7xLfRgPm2v",
    "organization_id": "org_011CZkZBj9RsYd3wNcHvKq6t"
  }
}

Pour voir ce qui a changé, récupérez le profil avec client.user_profiles.retrieve(), en utilisant data.id. Sa liste enforcement_actions affiche ses mesures ouvertes. Chaque mesure possède un type (restriction ou ban), un id, une reason, une heure opened_at, et une heure expires_at ou null. enforcement_status les résume : banned tant qu'un bannissement est ouvert, restricted tant qu'une autre mesure est ouverte, et unrestricted lorsqu'aucune ne l'est. Traitez toute autre valeur comme restricted.

Anthropic n'envoie un événement qu'après que le profil affiche le changement ; le profil que vous récupérez affiche donc ce changement ou un changement ultérieur. Les événements peuvent arriver en retard ou dans le désordre ; utilisez donc l'état actuel du profil, et non l'ordre d'arrivée des événements. Après user_profile.enforcement_action_resolved, la mesure résolue ne figure plus dans la liste. Une erreur 404 signifie que le profil a été supprimé.

Champs du point de terminaison

Un point de terminaison de webhook d'organisation possède les champs suivants :

{
  "id": "wep_011CZkZDf8HnUq2mTxRbVn4s",
  "url": "https://example.com/anthropic-webhooks",
  "name": "Enforcement actions",
  "description": "",
  "enabled_events": [
    "user_profile.enforcement_action_opened",
    "user_profile.enforcement_action_resolved"
  ],
  "state": "enabled",
  "disabled_reason": "",
  "created_at": "2026-10-20T19:00:00Z",
  "updated_at": "2026-10-20T19:00:00Z"
}

Une organisation peut avoir jusqu'à 32 points de terminaison de webhook d'organisation. Les points de terminaison de webhook désactivés comptent toujours dans ce total.

Livraisons

Les livraisons suivent la spécification Standard Webhooks. Chacune contient les en-têtes webhook-id, webhook-timestamp et webhook-signature. Avant de faire confiance à un événement, vérifiez sa signature avec le secret de signature du point de terminaison, à l'aide de n'importe quelle bibliothèque Standard Webhooks.

Renvoyez n'importe quel statut 2xx dans un délai de 5 secondes, et effectuez les traitements lents ensuite. Toute autre réponse, ou l'absence de réponse, compte comme une tentative échouée.

• Doublons : Un point de terminaison peut recevoir le même événement plusieurs fois, avec le même id d'événement (la même valeur que l'en-tête webhook-id). Dédupliquez sur cette valeur.

• Nouvelles tentatives : Si une livraison échoue, Anthropic la retente quelques fois au cours des minutes suivantes. Si toutes les tentatives échouent, Anthropic abandonne l'événement. Pour rattraper votre retard, listez vos profils par statut d'application, comme dans Avant votre premier événement.

• Désactivation automatique : Anthropic désactive un point de terminaison lorsque :

  • Il renvoie une redirection (3xx).
  • Son URL se résout en une adresse IP non publique.
  • Ses livraisons échouent de manière répétée.

  Anthropic ignore les événements destinés à un point de terminaison désactivé et ne les envoie pas ultérieurement.

Gérer les points de terminaison

Avec l'Admin API, vous pouvez effectuer les requêtes suivantes :

Lors d'une mise à jour, enabled_events remplace l'intégralité de la liste des types d'événements du point de terminaison. Une liste vide ne vide pas la liste : le point de terminaison conserve les types d'événements qu'il avait. Pour arrêter les livraisons, envoyez "state": "disabled" ou supprimez le point de terminaison.

Pour réactiver un point de terminaison, y compris après qu'Anthropic l'a désactivé, envoyez "state": "enabled" dans une requête de mise à jour.

Lorsque vous remplacez le secret de signature, l'ancien secret cesse immédiatement de fonctionner. Les livraisons effectuées à partir de ce moment, y compris les nouvelles tentatives pour des événements antérieurs, sont signées avec le nouveau secret ; mettez donc à jour votre récepteur sans attendre.

Envoyez l'en-tête anthropic-beta: webhooks-2026-10-07 avec chaque requête. Le SDK et la CLI l'envoient pour vous. Cet exemple liste les points de terminaison de votre organisation, en utilisant une clé Admin API provenant de ANTHROPIC_API_KEY.

client = anthropic.Anthropic()

endpoints = client.beta.organization.webhooks.list()

for endpoint in endpoints:
    print(f"{endpoint.id}: {endpoint.url} ({endpoint.state})")

En l'absence de points de terminaison, l'API renvoie une liste vide :

{
  "data": [],
  "has_more": false
}

Une liste renvoie jusqu'à 20 points de terminaison par défaut. Définissez limit pour en obtenir jusqu'à 100. Si has_more vaut true, passez le last_id de la réponse comme after_id pour obtenir la page suivante.

Cet exemple crée un point de terminaison qui reçoit les deux types d'événements :

client = anthropic.Anthropic()

endpoint = client.beta.organization.webhooks.create(
    url="https://example.com/anthropic-webhooks",
    name="Enforcement actions",
    enabled_events=[
        "user_profile.enforcement_action_opened",
        "user_profile.enforcement_action_resolved",
    ],
)

print(endpoint.id)

La réponse est le nouveau point de terminaison, tel qu'illustré dans Champs du point de terminaison, accompagné de son signing_secret.

Erreurs

Une requête renvoie une erreur 400 si :

• Son url ne respecte pas les règles décrites dans Champs du point de terminaison, ou une requête de création ne liste aucun type d'événement. Le message d'erreur indique le problème.
• Votre organisation n'a pas d'espace de travail par défaut.
• Les webhooks d'organisation ne sont pas disponibles pour votre organisation parce que son espace de travail par défaut utilise une clé de chiffrement gérée par le client. Le message d'erreur l'indique.
• Elle donnerait à votre organisation plus de 32 points de terminaison de webhook d'organisation.
• Elle place dans enabled_events un type d'événement autre que les deux décrits dans Types d'événements. Le message d'erreur liste les types acceptés.

Une requête renvoie une erreur 403 si le rôle de votre compte n'inclut pas l'autorisation requise par la requête. L'erreur nomme cette autorisation.

Une requête renvoie une erreur 404 si :

• Elle n'envoie pas l'en-tête anthropic-beta: webhooks-2026-10-07.
• Anthropic n'a pas activé les webhooks d'organisation pour votre organisation.
• La préparation HIPAA est activée pour votre organisation.
• Elle utilise un type d'identifiant que ces requêtes n'acceptent pas.
• Son webhook_endpoint_id ne correspond à aucun point de terminaison de votre organisation.

Une requête renvoie une erreur 409 si :

• Elle amènerait deux points de terminaison de webhook d'organisation activés à partager une URL.
• Une autre requête a modifié les points de terminaison de votre organisation au même moment. Réessayez la requête.

Compatibility