sumsub-manage-webhooks

Sumsub — クライアント Webhook の管理

ClientWebhook イベントサブスクリプションを一覧表示、取得、作成、更新します。読み取りには /resources/api/clientWebhooks、書き込みには /resources/api/agent/clientWebhooks を使用します。

エンドポイント

Verb	Path	Purpose
GET	/resources/api/clientWebhooks	テナント上の Webhook を一覧表示します。EntityResult<ClientWebhook>（{list: {items: [...] }}）を返します。サーバー側で古いものから最大 50 件に制限されます（getOldest50）。
GET	/resources/api/clientWebhooks/{id}	ID で Webhook を 1 件取得します。既知の ID から name を確認する場合や、書き込み後に反映された内容を検証する場合に使用します。
POST	/resources/api/agent/clientWebhooks	作成します。リクエスト本文に id を含めてはいけません。ID はサーバーが割り当てます。（モデルレイヤーでは内部的にアップサートを行いますが、リクエスト DTO は id を含まない ClientWebhookCreateRequest です。）
PATCH	/resources/api/agent/clientWebhooks	既存の Webhook を更新します（本文の id で指定）。DTO は ClientWebhookUpdateRequest です。

必要な権限：manageClientSettings。

パブリック API には DELETE はなく、/stats エンドポイントもありません。Webhook の削除や、Webhook ごとの配信統計の確認には Sumsub ダッシュボード UI を使用してください。

認証 — App Token とシークレット（サンドボックスのみ）

このスキルはパブリック Sumsub API を利用し、認証リファレンスに従って各リクエストに署名します。仕組みの詳細については、sumsub-api-auth スキルを参照してください。401 Invalid signature が発生した場合は、こちらをお読みください。

⚠️ サンドボックスのトークンのみ使用できます。 ここでは本番環境の App Token を受け入れたり、使用したりしないでください。ユーザーが提示した場合は拒否し、https://cockpit.sumsub.com/checkus/home?sbx=true でサンドボックス用のペアを生成するよう依頼してください（Connect Sumsub to your AI agent → Build & configure → Generate token）。トークンとシークレットは一度だけ表示されます。ダイアログを閉じる前に両方をコピーしてください。ヘルパースクリプトでもこの制約を適用しており、SUMSUB_ALLOW_PROD=1 が設定されていない限り、sbx: で始まらないトークンは拒否されます。

Var	Example
SUMSUB_APP_TOKEN	sbx:... — ダッシュボードで発行したサンドボックス用 App Token。
SUMSUB_SECRET_KEY	トークン作成時に一度だけ表示される、対応するシークレット。
SUMSUB_BASE	任意。デフォルトは https://api.sumsub.com です。

会話内でユーザーがすでに認証情報を提示している場合は、それを再利用してください。そうでない場合は、実行前に一度だけ確認してください。シークレットをそのままユーザーに返してはいけません。

サンドボックス限定の範囲 — 本番環境の Webhook は人が作成する必要があります

このスキルが受け入れるのはサンドボックス用 App Token のみであるため、このスキルで作成または更新する Webhook はすべてサンドボックスワークスペースに保存されます。Sumsub ではサンドボックスと本番環境は別々のテナントであり、「本番環境に昇格」する方法はありません。また、本物の Webhook を設定するために本番用トークンでこのスキルを再実行するのも適切な方法ではありません。

本番環境の Webhook を設定する段階になったら、次の手順に従ってください。

• ユーザーから依頼された場合でも、このスキルで設定すると申し出てはいけません。
• 本番用 App Token を求めたり、受け入れたりしてはいけません（スクリプトは SUMSUB_ALLOW_PROD=1 がなければ拒否します。また、その上書きを提案してはいけません）。
• 本番環境の Webhook（ターゲット URL、署名シークレット、イベントサブスクリプション、カスタムヘッダー）は、ユーザー本人が Sumsub ダッシュボードから直接設定する必要があると伝えてください（Integrations → Webhooks で、ワークスペースの切り替えを Production にします）。本番環境の Webhook 設定はセキュリティ上重要な操作です（署名シークレットは実際の PII 配信を認証します）。監査証跡には、設定した人が記録される必要があります。
• 適切なワークフローは、まずこのスキルでサンドボックスを使って試作し、ユーザーが希望する最終仕様（イベント一覧、ヘッダー、署名アルゴリズム）をまとめてから、その仕様を通常のドキュメントとして人に引き渡し、本番環境で再現してもらうことです。

サブコマンド

manage_webhooks.sh がオーケストレーターです。

manage_webhooks.sh list                       # GET all webhooks (table summary; capped at 50)
manage_webhooks.sh list --json                # raw JSON of all webhooks
manage_webhooks.sh get <webhookId>            # one webhook (filtered from the list)
manage_webhooks.sh create <spec.json>         # POST without id  (compact spec → ClientWebhook)
manage_webhooks.sh update <spec.json>         # POST with id     (spec MUST contain id)

create と update は、どちらも build_webhook_payload.py を呼び出して簡潔な仕様を展開します。

送信する前に：target がパブリックに到達可能であることを確認してください

Sumsub は独自のインフラストラクチャから Webhook を送信するため、target URL はパブリックインターネットから名前解決でき、接続を受け付ける必要があります。よくある注意点：ローカルで開発中に、http://localhost:3000/webhook（または 127.0.0.1、0.0.0.0、::1）を貼り付けてしまうケースです。Sumsub は作成時に URL を受け付けますが、配信はすべて失敗します。また、このような targets はスキルのペイロードビルダーによって事前に拒否されます。

ユーザーが localhost のような URL を指定した場合は、送信しないでください。代わりに、Webhook を作成する前に、パブリックトンネルを使ってローカルサーバーを公開する方法を案内してください。

1. ngrok を提案します（最も一般的な選択肢です）。macOS では brew install ngrok/ngrok/ngrok を実行します。その他のプラットフォームでは、リンクからダウンロードします。初めて利用する場合は、無料の ngrok アカウントを作成して認証トークンを取得し、ngrok config add-authtoken <TOKEN> を一度実行する必要があります。
2. ローカルの Webhook レシーバーが待ち受けているポートを尋ねます（通常は 3000／8080／4000）。
3. 別のターミナルで ngrok http <port> を実行し、そのまま開いておくよう伝えます。
4. ngrok は Forwarding https://<random>.ngrok-free.app -> http://localhost:<port> の行を表示します。https://...ngrok-free.app の部分がパブリック URL です。
5. レシーバーの Webhook パス（例：/webhook、/sumsub）を追加し、完全な URL を target として使用します。その後、create サブコマンドを再実行します。

注意点として伝える内容：無料の ngrok プランでは、ngrok を再起動するたびにパブリック URL が変わります。そのため、セッションごとに Webhook を再度 update する必要があります（既存の id と新しい target を指定して POST します）。予約済みドメイン（有料）または --domain=<your-subdomain> を使うと、URL を固定できます。ユーザーが希望する場合の代替手段として、Cloudflare Tunnel（cloudflared tunnel）、Tailscale Funnel、localtunnel もあります。考え方も手順も同じです。

create／update の簡易仕様

# Identity (omit on create; required on update)
id: 698bfc...                  # id from a previous list / create response

# Display + addressing
name: "Production webhook"     # required (no min length but the dashboard expects something)
description: "Sends KYC events to our backend"
target: "https://example.com/sumsub/webhook"   # required — destination URL (or slack / email / telegram address depending on targetType)
targetType: http               # http | email | slack | telegram   (default: http)

# Subscription
types:                         # required — event-type strings (see "Event types" below)
  - applicantReviewed
  - applicantPending
  - applicantOnHold
  - applicantCreated
applicantType: individual      # individual | company   (omit to subscribe to both)
sourceKeys: []                 # optional — restrict to specific source keys

# Auth + delivery
secretKey: "..."               # HMAC secret used to sign payloads
signatureAlgorithm: HMAC_SHA256_HEX  # HMAC_SHA1_HEX | HMAC_SHA256_HEX | HMAC_SHA512_HEX  (default: SHA256)
headers:                       # optional extra HTTP headers added to each delivery
  - { key: "X-Source", value: "sumsub" }
  - { key: "Authorization", value: "Bearer ${MY_TOKEN}" }   # caller substitutes before sending

# Lifecycle flags
notResendFailedWebhooks: false # default false; true = no automatic retries on delivery failure

ビルダーは列挙値（targetType、signatureAlgorithm、applicantType）を検証し、空の types を拒否して、key／value の形式が ClientWebhookHeader に一致するよう headers をラップします。不明なキーはそのまま通過します（エスケープハッチ）。

イベントタイプ（types[]）

OpenAPI では、types は自由形式の string[] として定義されています。以下の名前は、一般的に送信される Sumsub イベントを網羅しています。不明なイベントタイプはサーバー側でエラーなく受け入れられますが、Webhook は呼び出されないため、API では入力ミスを検出できません。

グループ	イベントタイプ	発火するタイミング
申請者のライフサイクル	applicantCreated	新しい申請者が作成されたとき
	applicantPrechecked	事前審査が完了したとき
	applicantPending	審査に提出されたとき
	applicantReviewed	最終審査結果（GREEN / RED）が確定したとき
	applicantOnHold	審査が保留または一時停止されたとき
	applicantActivated	申請者が有効化されたとき
	applicantDeactivated	申請者が無効化されたとき
	applicantReset	検証がリセットされたとき（再試行）
	applicantLevelChanged	レベルが再割り当てされたとき
	applicantTagsChanged	タグが追加または削除されたとき
	applicantPersonalInfoChanged	個人情報が編集されたとき
	applicantDeleted	申請者が削除されたとき
	applicantPersonalDataDeleted	GDPR に基づく個人データの消去が実行されたとき
アクションワークフロー	applicantActionPending / applicantActionReviewed / applicantActionOnHold	アクションフローのイベント
ワークフロー	applicantWorkflowCompleted	ワークフローの実行が完了したとき（applicantWorkflowRunCompleted ではありません）
ビデオ本人確認	videoIdentStatusChanged	ライブステータスが更新されたとき
	videoIdentCompositionCompleted	録画の組み立てが完了したとき
KYT（申請者単位）	applicantKytTxnApproved / applicantKytTxnRejected / applicantKytTxnReviewed / applicantKytTxnDeleted / applicantKytTxnDataChanged / applicantKytTxnAwaitingUser / applicantKytOnHold	申請者単位のトランザクション監視イベント
KYT（ケース単位）	kytCaseCreated / kytCaseStatusChanged / kytCaseReviewed	KYT のケース管理イベント（kytCaseUpdated ではなく、kytCaseStatusChanged です）
AML ケース	amlCaseApproved / amlCaseRejected / amlCaseOnHold	AML ケースの処理結果イベント
トラベルルール	travelRuleAction	トラベルルールのライフサイクルイベント
KYB	kybCompanyActivity	KYB の継続的なモニタリングイベント

このスキルは、呼び出し元が記述した内容をそのまま転送します。Sumsub がこのリストの更新よりも速くイベントを追加する可能性があるため、クライアント側での検証は行いません。

出力

• list — id、name、target、disabled、types[]、applicantType、signatureAlgorithm、createdAt を含むテーブル。
• get — Webhook 1 件分の完全な JSON（防御策として、出力では secretKey を伏せています）。
• create / update — 保存された ClientWebhook（作成時はサーバーが割り当てた id を含む）と、1 行の概要。

使用例

• examples/basic-http.json — 最小限の Webhook：HTTPS エンドポイント、申請者のライフサイクルイベント 4 件、SHA-256 署名。
• examples/with-headers-and-restrictions.json — 特定の sourceKey を対象とする幅広いイベントセットと、カスタム HTTP ヘッダー。
• examples/legacy-sha1.json — SHA1 署名付きの Webhook。すでに SHA1 を検証している受信側向けです。
• examples/update-existing.json — 基本例と同じですが、id を設定して更新パスを示しています。

関連項目

• references/webhook-schema.md — ClientWebhook スキーマ全体、すべての列挙値、注意事項（シークレットは書き込み専用ではないこと、署名の仕組み）。
• Sumsub のドキュメント：Webhook system、Webhook event types、Verify webhook signatures。