shoplazza-webhook

shoplazza CLI — webhook モジュール

最重要 — 何よりも先に、../shoplazza-common/SKILL.md を Read してください。 このファイルでは、アクセス階層、出力エンベロープ（.data）、--dry-run、 --jq、schema、api rest、認証／プロファイル、安全プロトコルなど、横断的な仕組みをすべて扱います。このファイルでは webhook ドメインのみを扱い、それらについては繰り返しません。

概要

webhook モジュールはイベントサブスクリプションを管理します。webhook は、ストアのイベントトピック（例： orders/create）をアドレス（イベント発生時にプラットフォームが呼び出す HTTPS エンドポイント）に紐づけます。 このモジュールは仕様に記載されたリーフコマンドのみで構成され、+shortcuts はありません。CRUD と件数取得に対応します。

コマンド一覧

目的 → コマンド。正式なパラメーター／ボディは shoplazza schema webhook.<cmd> で確認できます。

ユーザーの目的	コマンド
イベントをサブスクライブする（作成）	webhook create --data '{"webhook":{"topic":"<event>","address":"<https-url>"}}'
すべての webhook を一覧表示する	webhook list
webhook の件数を取得する（任意で絞り込み）	webhook count --params '{"address":"<url>","topic":"<event>"}'（パラメーターは省略可能）
webhook を 1 件取得する	webhook get --params '{"id":"<id>"}'
webhook のアドレス／トピックを更新する	webhook update --params '{"id":"<id>"}' --data '{"webhook":{"address":"<url>","topic":"<event>"}}'
webhook を削除する（破壊的操作 → 先に --dry-run）	webhook delete --params '{"id":"<id>"}' --dry-run

イベントトピックは orders/create、orders/fulfilled、products/update などの形式です。トピックの完全な一覧はバイナリから確認できません。トピックは shoplazza schema webhook.create または Open Platform のドキュメントで確認してください。推測で作成しないでください。

リクエストへの対応

1. 目的を該当するリーフコマンドに対応させます（ここにショートカットはありません）。
2. create には必須フィールドが 2 つあります。いずれかが不足している場合は、必ず AskUserQuestion で確認し、決して捏造しないでください。必要なのはイベントトピックとアドレス（HTTPS エンドポイント）です。update／get／delete では webhook の id が必須です。
3. 必須フィールドが揃っていれば、create／update はそのまま安全に実行できます（サブスクリプションによって金銭が移動することはありません）。ユーザーから依頼された場合にのみ、先に --dry-run を使います。
4. delete は破壊的操作です。イベント配信が通知なく停止し、元に戻せません。shoplazza-common の安全プロトコルに従い、先に --dry-run を実行し、どのサブスクリプションか（id だけでなく、トピックとアドレス）を改めて伝えたうえで、そこで停止してユーザーの承認を待ちます。

対象範囲

イベント／注文／商品に関する依頼のように見えて、実際にはこのモジュールが担当するケース：

注文／商品に関する依頼の例	実際の担当	コマンド
「注文発送後に自分のシステムへ自動通知する」／注文の発送時に自分のシステムへ通知する	ここ（webhook） — サブスクリプションです	webhook create --data '{"webhook":{"topic":"orders/fulfilled",…}}'
「商品が更新されたら通知してほしい」／商品の更新時に通知を受け取る	ここ（webhook）	webhook create --data '{"webhook":{"topic":"products/update",…}}'

イベントのサブスクライブには orders／products コマンドではなく、webhook を使います。（event-webhook の振り分け競合への対応です。）

権限 · スコープ

認可はドメイン単位です。付与するには auth login --domain webhook を実行します。正確なスコープ文字列は shoplazza auth scopes で確認してください。

注意事項

ドメイン固有の内容のみを記載しています（汎用ルールは shoplazza-common にあります）。

症状	原因	対処
topic を推測したところ、拒否された	トピックの列挙値がバイナリのヘルプに含まれていません	schema webhook.create／Open Platform のドキュメントで確認してください。不明な場合はユーザーに尋ね、推測で作成しないでください
create が失敗する	webhook ボディでは topic と address の両方が必須です	--data '{"webhook":{"topic":"…","address":"…"}}'
address が拒否される	エンドポイントは到達可能な HTTPS URL である必要があります	完全な https:// URL を指定します

レシピ

# 1. Subscribe: push order-created events to an endpoint
webhook create --data '{"webhook":{"topic":"orders/create","address":"https://api.myapp.com/hooks/orders"}}'

# 2. List current subscriptions
webhook list

# 3. Update a webhook's address
webhook update --params '{"id":"246"}' --data '{"webhook":{"address":"https://new.example.com/hook"}}'

# 4. Delete a subscription: look up what it is, preview, then STOP for the user's go-ahead
webhook get --params '{"id":"135"}' --jq '.data.webhook | {topic, address}'
webhook delete --params '{"id":"135"}' --dry-run

# 5. Count webhooks pointing at an address
webhook count --params '{"address":"https://api.myapp.com/hooks"}'

参考資料

• コマンドごとのフラグ：shoplazza webhook <cmd> --help
• パラメーター／ボディ／レスポンス：shoplazza schema webhook.<cmd>
• 横断的な仕組み（認証／階層／出力エンベロープ／--dry-run／安全性）：../shoplazza-common/SKILL.md