組織Webhook

「organization webhook endpoint」（組織Webhookエンドポイント）は、Anthropicが組織のユーザープロファイルのいずれかを制限または利用禁止にしたとき、およびその制限または利用禁止が終了したときにイベントを受け取ります。これは/v1/organizations/webhooks配下のAdmin APIで管理します。

組織のメンバーであれば誰でもAPIで組織Webhookエンドポイントを一覧表示および閲覧できますが、エンドポイントの作成、変更、削除、または署名シークレットの置き換えができるのは、admin、owner、またはprimary ownerのロールを持つメンバーのみです。

始める前に

以下が必要です。

• 組織Webhookが有効になっており、HIPAA対応が有効になっていないClaude API上の組織。アクセスをリクエストするには、Anthropicのアカウントチームにお問い合わせください。
• 次のいずれかの認証情報：
  • Admin APIキー。
  • org:adminスコープを持つOAuthベアラートークン。
  • ワークスペースにスコープされていない個人またはサービスアカウントのキー。

イベントタイプ

組織Webhookエンドポイントは2つのイベントタイプを受け付けます。どちらもユーザープロファイルに対する「enforcement action」（措置）に関するものです。措置とは、プロファイルが表すエンドカスタマーに対してAnthropicが課す制限または利用禁止のことです。

プロファイルを削除すると、そのプロファイルの有効な措置はuser_profile.enforcement_action_resolvedイベントなしで終了します。

最初のイベントの前に

組織で措置が有効になるまで、プロファイルにはenforcement_statusおよびenforcement_actionsフィールドがありません。それまでの間、およびanthropic-betaヘッダーにuser-profiles-2026-09-04またはそれ以前の値を含むリクエストでは、レスポンスにこれらのフィールドが含まれず、enforcement_status[]リストフィルターは400を返します。これらのフィールドを取得するには、リクエストからその値を削除してください。

Anthropicが組織で措置とイベント配信を有効にする前、またはエンドポイントを登録する前に措置が開始された場合、その措置に対するuser_profile.enforcement_action_openedイベントは届きません。措置はプロファイル上には引き続き表示されます。これらの措置を見つけるには、enforcement_status[]=restrictedおよびenforcement_status[]=bannedを指定してプロファイルを一覧表示してください。リストが終わる前に、レスポンスがlimitより少ないプロファイルを返したり、まったく返さなかったりする場合があるため、next_pageがnullになるまでページのリクエストを続けてください。

イベントの内容

イベントには措置やプロファイルそのものではなく、IDが含まれます。data.idはプロファイルのIDで、data.enforcement_action_idは措置のIDであり、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"
  }
}

何が変わったかを確認するには、data.idを使用してclient.user_profiles.retrieve()でプロファイルを取得します。そのenforcement_actionsリストには有効な措置が表示されます。各措置には、type（restrictionまたはban）、id、reason、opened_atの時刻、およびexpires_atの時刻またはnullがあります。enforcement_statusはそれらを要約したもので、利用禁止が有効な間はbanned、その他の措置が有効な間はrestricted、何もない場合はunrestrictedになります。その他の値はrestrictedとして扱ってください。

Anthropicはプロファイルに変更が反映された後にのみイベントを送信するため、取得したプロファイルにはその変更またはそれ以降の変更が反映されています。イベントは遅れて届いたり、順序が入れ替わって届いたりする場合があるため、イベントが届いた順序ではなく、プロファイルの現在の状態を使用してください。user_profile.enforcement_action_resolvedの後、解決された措置はリストに含まれなくなります。404はプロファイルが削除されたことを意味します。

エンドポイントのフィールド

組織Webhookエンドポイントには次のフィールドがあります。

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

1つの組織は最大32個の組織Webhookエンドポイントを持つことができます。無効化されたWebhookエンドポイントもこの合計に含まれます。

配信

配信はStandard Webhooks仕様に従います。各配信にはwebhook-id、webhook-timestamp、およびwebhook-signatureヘッダーが含まれます。イベントを信頼する前に、任意のStandard Webhooksライブラリを使用して、エンドポイントの署名シークレットでその署名を検証してください。

5秒以内に任意の2xxステータスを返し、時間のかかる処理はその後に行ってください。それ以外のレスポンス、またはレスポンスがない場合は、失敗した試行としてカウントされます。

• 重複： エンドポイントは同じイベントを、同じイベントid（webhook-idヘッダーと同じ値）で複数回受け取る場合があります。これを使って重複を排除してください。

• 再試行： 配信が失敗した場合、Anthropicはその後数分間にわたって数回再試行します。すべての試行が失敗した場合、Anthropicはそのイベントを破棄します。取りこぼしを補うには、最初のイベントの前にと同様に、措置ステータスでプロファイルを一覧表示してください。

• 自動無効化： Anthropicは次の場合にエンドポイントを無効にします。

  • リダイレクト（3xx）を返した場合。
  • URLが非公開のIPアドレスに解決される場合。
  • 配信が失敗し続ける場合。

  Anthropicは無効化されたエンドポイントへのイベントをスキップし、後から送信することはありません。

エンドポイントの管理

Admin APIでは、次のリクエストを行うことができます。

更新では、enabled_eventsはエンドポイントのイベントタイプのリスト全体を置き換えます。空のリストではリストはクリアされず、エンドポイントは既存のイベントタイプを保持します。配信を停止するには、"state": "disabled"を送信するか、エンドポイントを削除してください。

Anthropicによって無効化された後も含め、エンドポイントを再度有効にするには、更新リクエストで"state": "enabled"を送信してください。

署名シークレットを置き換えると、古いシークレットは直ちに機能しなくなります。それ以降の配信は、以前のイベントの再試行も含めて新しいシークレットで署名されるため、すぐにレシーバーを更新してください。

すべてのリクエストでanthropic-beta: webhooks-2026-10-07ヘッダーを送信してください。SDKとCLIは自動的にこれを送信します。この例では、ANTHROPIC_API_KEYのAdmin APIキーを使用して、組織のエンドポイントを一覧表示します。

client = anthropic.Anthropic()

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

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

エンドポイントがない場合、APIは空のリストを返します。

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

一覧表示では、デフォルトで最大20個のエンドポイントが返されます。最大100個を取得するにはlimitを設定してください。has_moreがtrueの場合は、レスポンスのlast_idをafter_idとして渡すと次のページを取得できます。

この例では、両方のイベントタイプを受け取るエンドポイントを作成します。

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)

レスポンスは、エンドポイントのフィールドに示すとおりの新しいエンドポイントに、そのsigning_secretを加えたものです。

エラー

次の場合、リクエストは400を返します。

• urlがエンドポイントのフィールドのルールを満たしていない場合、または作成リクエストでイベントタイプが指定されていない場合。エラーメッセージに問題点が示されます。
• 組織にデフォルトワークスペースがない場合。
• 組織のデフォルトワークスペースが顧客管理の暗号化キーを使用しているため、組織で組織Webhookを利用できない場合。エラーメッセージにその旨が示されます。
• 組織の組織Webhookエンドポイントが32個を超えることになる場合。
• enabled_eventsにイベントタイプの2つ以外のイベントタイプを指定した場合。エラーメッセージに受け付けられるタイプが一覧表示されます。

アカウントのロールにリクエストに必要な権限が含まれていない場合、リクエストは403を返します。エラーにはその権限の名前が示されます。

次の場合、リクエストは404を返します。

• anthropic-beta: webhooks-2026-10-07ヘッダーを送信していない場合。
• Anthropicが組織で組織Webhookを有効にしていない場合。
• 組織でHIPAA対応が有効になっている場合。
• これらのリクエストが受け付けない種類の認証情報を使用している場合。
• webhook_endpoint_idが組織内のエンドポイントと一致しない場合。

次の場合、リクエストは409を返します。

• 有効な2つの組織Webhookエンドポイントが同じURLを共有することになる場合。
• 別のリクエストが同時に組織のエンドポイントを変更した場合。リクエストを再試行してください。

Compatibility