自社サービスにClaudeを組み込んで顧客に提供している中小SaaSでは、顧客1社の不正利用が原因で自社全体のAPIが止まるリスクがあります。ユーザープロファイルで顧客単位に分離しても、制限やBANが発生したことに自社が気づけなければ、問い合わせ対応が後手に回ります。この記事は、Anthropicの組織webhook(ベータ)を受信して、制限・BANを検知する小さな受信基盤の作り方をまとめます。
組織webhookで何が通知されるのか
組織webhookは、ユーザープロファイルへの制限やBANの開始と終了を通知する仕組みです。イベント種別は2つだけで、通知にはIDしか含まれません。
通知されるイベントは user_profile.enforcement_action_opened と user_profile.enforcement_action_resolved の2種類です。ペイロードの data.id はプロファイルID(uprof_)、data.enforcement_action_id は対応ID(enac_)で、理由や期限は入っていません。
詳細は GET /v1/user_profiles/{id} で取得し、enforcement_status(unrestricted / restricted / banned)と enforcement_actions を読みます。ベータヘッダー webhooks-2026-10-07 が必要で、利用には営業窓口への申請が要ります。現時点の公式ドキュメントには、イベント配信がまだ稼働しておらず、登録しても何も届かないと注記があります。受信側の実装は先に進められますが、本番の監視は後述の照合ジョブを主、webhookを補助として設計してください。
どう署名を検証し、5秒以内に応答するか
配信はStandard Webhooks仕様に従い、署名検証と5秒以内の2xx返却が求められます。検証は受け取った生のバイト列で行い、処理は応答後に回します。
各配信には webhook-id、webhook-timestamp、webhook-signature の3ヘッダーが付きます。仕様上、署名対象は id.timestamp.payload を連結した文字列で、HMAC-SHA256(v1 接頭辞)です。JSONを再整形すると署名が合わなくなるため、パース前の生ボディで検証します。
実装の要点は次のとおりです。
- 署名はライブラリで検証し、比較は定数時間で行う
- 署名ヘッダーには複数の署名が並ぶことがあり、1つでも一致すれば受理する(鍵ローテーション対応)
webhook-timestampが現在時刻から大きくずれた配信は拒否する- 検証後は永続キューに積んで即座に2xxを返し、プロファイル取得などの重い処理は後続のワーカーで行う
- シークレットは
whsec_で始まり、作成時と再生成時のレスポンスにしか含まれないため、受け取った時点で秘匿ストアに保存する
シークレットを再生成すると旧シークレットは即座に失効し、再送分も新シークレットで署名されます。受信側の更新が遅れると正規の配信を落とすので、再生成は受信側の設定変更とセットで手順化します。
重複・順序逆転・取りこぼしにどう備えるか
同じイベントが複数回届き、順序も前後し、全再送に失敗すると破棄されます。状態の正は常にプロファイルAPIの現在値に置きます。
公式ドキュメントが明示している挙動は3点です。
- 重複: 同じイベントIDで複数回届くことがある。
webhook-idで重複排除する - 順序: 遅延や順序逆転があり得る。到着順ではなくプロファイルの現在状態を信頼する
- 再送: 失敗した配信は数分間リトライされ、全部失敗するとイベントは破棄される
さらに、エンドポイントが自動で無効化される条件があります。3xxリダイレクトを返した場合、URLが非公開IPに解決された場合、配信失敗が続いた場合です。無効化中のイベントは、後から送られません。
したがって受信ハンドラは「通知を受けたら該当プロファイルを再取得して状態を上書きする」だけの冪等な処理にします。加えて、定期の照合ジョブを持ちます。GET /v1/user_profiles に enforcement_status[]=restricted と enforcement_status[]=banned を指定して一覧し、next_page が null になるまでページを辿ります。公式は、limit より少ない件数や空の応答がページ途中で返り得ると注記しているため、件数ではなく next_page で終端を判定します。また enforcement_status の変化は updated_at に反映されるとは限らないので、前回値との差分で検知します。
中小SaaSの最小構成はどうなるか
最小構成は、受信エンドポイント、キュー、照合ジョブ、通知の4点です。エンドポイントの有効状態は定期的に確認します。
- 受信: 署名検証、イベントID重複排除、キュー投入、2xx返却
- ワーカー: プロファイル再取得、自社の顧客台帳と突き合わせ、状態を保存
- 照合ジョブ: 1日数回、制限・BAN中のプロファイルを全件一覧して台帳と差分を取る。初回に既存の制限を拾う役目も兼ねる
- 通知: 自社の顧客サポートへ、顧客名・
reason・expires_atを通知する。未知のenforcement_statusはrestrictedとして扱う - 健全性確認:
GET /v1/organizations/webhooksでstateとdisabled_reasonを見て、無効化を検知する
制約も押さえておきます。登録できるエンドポイントは最大32件、URLはポート443のHTTPSで公開ドメイン名が必要です。組織のデフォルトワークスペースが顧客管理暗号鍵(CMEK)を使う場合、およびHIPAA対応を有効にしている場合は利用できません。登録・変更・削除と署名シークレット再生成は admin / owner / primary owner のロールに限られます。
参考
- Organization webhooks — Claude Platform Docs
- User profiles — Claude Platform Docs
- Standard Webhooks 仕様
- Release notes — Claude Platform Docs
まとめ
組織webhookは、顧客単位の制限・BANを自社が即座に把握するための通知です。配信が稼働していない現状では、照合ジョブを主、webhookを補助にし、署名検証・重複排除・冪等な再取得の受信側を先に用意しておくのが堅実です。顧客別の統制を含むClaude基盤の運用設計は、Kuuの中小・成長企業向けAI導入支援までご相談ください。
