Organisations-Webhooks

Ein Organisations-Webhook-Endpunkt empfängt ein Event, wenn Anthropic eines der Benutzerprofile deiner Organisation einschränkt oder sperrt und wenn die Einschränkung oder Sperre endet. Du verwaltest ihn mit der Admin API unter /v1/organizations/webhooks.

Jedes Mitglied deiner Organisation kann Organisations-Webhook-Endpunkte mit der API auflisten und ansehen, aber nur Mitglieder mit der Rolle Admin, Owner oder Primary Owner können sie erstellen, ändern oder löschen oder ihr Signatur-Secret ersetzen.

Bevor du beginnst

Du benötigst Folgendes:

• Eine Organisation auf der Claude API, bei der Organisations-Webhooks aktiviert sind und bei der HIPAA-Bereitschaft nicht aktiviert ist. Um Zugang anzufordern, kontaktiere dein Anthropic-Account-Team.
• Eine dieser Arten von Anmeldedaten:
  • Einen Admin-API-Key.
  • Ein OAuth-Bearer-Token mit dem Scope org:admin.
  • Einen persönlichen oder Service-Account-Key, der nicht auf einen Workspace beschränkt ist.

Event-Typen

Organisations-Webhook-Endpunkte akzeptieren zwei Event-Typen. Beide betreffen „enforcement actions" (Durchsetzungsmaßnahmen) gegen Benutzerprofile. Eine Durchsetzungsmaßnahme ist eine Einschränkung oder Sperre, die Anthropic gegen den Endkunden verhängt, den ein Profil repräsentiert.

Das Löschen eines Profils beendet seine offenen Maßnahmen ohne ein user_profile.enforcement_action_resolved-Event.

Vor deinem ersten Event

Deine Profile haben die Felder enforcement_status und enforcement_actions erst, wenn Durchsetzungsmaßnahmen für deine Organisation aktiviert sind. Bis dahin, und bei jeder Anfrage, deren anthropic-beta-Header user-profiles-2026-09-04 oder einen früheren Wert enthält, lassen die Antworten die Felder weg, und der Listenfilter enforcement_status[] gibt einen 400 zurück. Um die Felder zu erhalten, entferne diesen Wert aus deinen Anfragen.

Wenn eine Durchsetzungsmaßnahme eingeleitet wurde, bevor Anthropic Durchsetzungsmaßnahmen und die Event-Zustellung für deine Organisation aktiviert hat oder bevor du deinen Endpunkt registriert hast, erhältst du dafür kein user_profile.enforcement_action_opened-Event. Die Maßnahme erscheint trotzdem im Profil. Um diese Maßnahmen zu finden, liste deine Profile auf mit enforcement_status[]=restricted und enforcement_status[]=banned. Eine Antwort kann weniger Profile als limit oder gar keine zurückgeben, bevor die Liste endet, also fordere weiter Seiten an, bis next_page null ist.

Was ein Event enthält

Events enthalten IDs, nicht die Maßnahme oder das Profil. data.id ist die ID des Profils, und data.enforcement_action_id ist die ID der Maßnahme, die mit enac_ beginnt:

{
  "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"
  }
}

Um zu sehen, was sich geändert hat, rufe das Profil ab mit client.user_profiles.retrieve() und verwende dabei data.id. Seine Liste enforcement_actions zeigt seine offenen Maßnahmen. Jede Maßnahme hat einen type (restriction oder ban), eine id, einen reason, einen opened_at-Zeitpunkt und einen expires_at-Zeitpunkt oder null. enforcement_status fasst sie zusammen: banned, solange eine Sperre offen ist, restricted, solange eine andere Maßnahme offen ist, und unrestricted, wenn keine offen ist. Behandle jeden anderen Wert als restricted.

Anthropic sendet ein Event erst, wenn das Profil die Änderung zeigt, daher zeigt das abgerufene Profil diese Änderung oder eine spätere. Events können verspätet oder in falscher Reihenfolge ankommen, also verwende den aktuellen Zustand des Profils, nicht die Reihenfolge, in der Events ankommen. Nach user_profile.enforcement_action_resolved ist die abgeschlossene Maßnahme nicht mehr in der Liste. Ein 404 bedeutet, dass das Profil gelöscht wurde.

Endpunkt-Felder

Ein Organisations-Webhook-Endpunkt hat diese Felder:

{
  "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"
}

Eine Organisation kann bis zu 32 Organisations-Webhook-Endpunkte haben. Deaktivierte Webhook-Endpunkte zählen weiterhin zu dieser Gesamtzahl.

Zustellungen

Zustellungen folgen der Spezifikation Standard Webhooks. Jede enthält die Header webhook-id, webhook-timestamp und webhook-signature. Bevor du einem Event vertraust, verifiziere seine Signatur mit dem Signatur-Secret des Endpunkts, mit einer beliebigen Standard-Webhooks-Bibliothek.

Gib innerhalb von 5 Sekunden einen beliebigen 2xx-Status zurück und erledige zeitaufwendige Arbeit danach. Jede andere Antwort oder keine Antwort zählt als fehlgeschlagener Versuch.

• Duplikate: Ein Endpunkt kann dasselbe Event mehr als einmal empfangen, mit derselben Event-id (demselben Wert wie der webhook-id-Header). Dedupliziere anhand dieser ID.

• Wiederholungsversuche: Wenn eine Zustellung fehlschlägt, wiederholt Anthropic sie einige Male in den nächsten Minuten. Wenn jeder Versuch fehlschlägt, verwirft Anthropic das Event. Um aufzuholen, liste deine Profile nach Durchsetzungsstatus auf, wie in Vor deinem ersten Event beschrieben.

• Automatische Deaktivierung: Anthropic deaktiviert einen Endpunkt, wenn:

  • Er eine Weiterleitung (3xx) zurückgibt.
  • Seine URL zu einer nicht öffentlichen IP-Adresse aufgelöst wird.
  • Seine Zustellungen wiederholt fehlschlagen.

  Anthropic überspringt Events für einen deaktivierten Endpunkt und sendet sie auch später nicht.

Endpunkte verwalten

Mit der Admin API kannst du diese Anfragen stellen:

Bei einer Aktualisierung ersetzt enabled_events die gesamte Liste der Event-Typen des Endpunkts. Eine leere Liste leert die Liste nicht: Der Endpunkt behält die Event-Typen, die er hatte. Um Zustellungen zu stoppen, sende "state": "disabled" oder lösche den Endpunkt.

Um einen Endpunkt wieder zu aktivieren, auch nachdem Anthropic ihn deaktiviert hat, sende "state": "enabled" in einer Aktualisierungsanfrage.

Wenn du das Signatur-Secret ersetzt, funktioniert das alte Secret sofort nicht mehr. Zustellungen ab diesem Zeitpunkt, einschließlich der Wiederholungsversuche für frühere Events, werden mit dem neuen Secret signiert, also aktualisiere deinen Empfänger sofort.

Sende den Header anthropic-beta: webhooks-2026-10-07 mit jeder Anfrage. Das SDK und die CLI senden ihn für dich. Dieses Beispiel listet die Endpunkte deiner Organisation auf und verwendet dabei einen Admin-API-Key aus ANTHROPIC_API_KEY.

client = anthropic.Anthropic()

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

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

Ohne Endpunkte gibt die API eine leere Liste zurück:

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

Eine Liste gibt standardmäßig bis zu 20 Endpunkte zurück. Setze limit, um bis zu 100 zu erhalten. Wenn has_more true ist, übergib die last_id der Antwort als after_id, um die nächste Seite zu erhalten.

Dieses Beispiel erstellt einen Endpunkt, der beide Event-Typen empfängt:

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)

Die Antwort ist der neue Endpunkt, wie in Endpunkt-Felder gezeigt, plus sein signing_secret.

Fehler

Eine Anfrage gibt einen 400 zurück, wenn:

• Ihre url die Regeln in Endpunkt-Felder nicht erfüllt oder eine Erstellungsanfrage keine Event-Typen auflistet. Die Fehlermeldung gibt an, was falsch ist.
• Deine Organisation keinen Standard-Workspace hat.
• Organisations-Webhooks für deine Organisation nicht verfügbar sind, weil ihr Standard-Workspace einen kundenverwalteten Verschlüsselungsschlüssel verwendet. Die Fehlermeldung weist darauf hin.
• Sie deiner Organisation mehr als 32 Organisations-Webhook-Endpunkte geben würde.
• Sie einen anderen Event-Typ als die beiden in Event-Typen in enabled_events angibt. Die Fehlermeldung listet die akzeptierten Typen auf.

Eine Anfrage gibt einen 403 zurück, wenn die Rolle deines Kontos nicht die Berechtigung enthält, die die Anfrage benötigt. Der Fehler nennt diese Berechtigung.

Eine Anfrage gibt einen 404 zurück, wenn:

• Sie den Header anthropic-beta: webhooks-2026-10-07 nicht sendet.
• Anthropic Organisations-Webhooks für deine Organisation nicht aktiviert hat.
• Deine Organisation HIPAA-Bereitschaft aktiviert hat.
• Sie eine Art von Anmeldedaten verwendet, die diese Anfragen nicht akzeptieren.
• Ihre webhook_endpoint_id keinem Endpunkt in deiner Organisation entspricht.

Eine Anfrage gibt einen 409 zurück, wenn:

• Sie dazu führen würde, dass zwei aktivierte Organisations-Webhook-Endpunkte dieselbe URL verwenden.
• Eine andere Anfrage gleichzeitig die Endpunkte deiner Organisation geändert hat. Wiederhole die Anfrage.

Compatibility