commerce-app-webhooks

Commerce App Webhook の設定

既存の app.commerce.config.ts に Webhook インターセプターを追加または変更します。 Webhook は Commerce の操作に割り込みます。操作の実行前または実行後に、入力の検証、データの追加、動作の変更ができます。 その他の拡張領域（イベント、ビジネス設定）は、それぞれのスキルで個別に追加します。

前提条件

• アプリがスキャフォールディングされ、初期化済みであることを確認してください。設定ファイルが存在するだけでは不十分です。以下の両方が必要です。
  • プロジェクトのルートに app.commerce.config.ts があること、および
  • プロジェクトが初期化済みであること。これは、生成された src/commerce-extensibility-1/ ディレクトリとインストール済みの node_modules（@adobe/aio-commerce-lib-app 依存関係）で確認できます。
• app.commerce.config.ts が存在しない場合は、停止して最初に commerce-app-init を実行してください（設定ファイルを書き込み、その後初期化を実行します）。
• 設定ファイルは存在するが、プロジェクトが初期化されていない場合（src/commerce-extensibility-1/ または node_modules がない場合）は、続行する前に npx @adobe/aio-commerce-lib-app init を実行してください。init は冪等です。既存の設定ファイルを検出して対話形式のプロンプトをスキップし、依存関係をインストールしてプロジェクトファイルを生成します。
• アクションを TypeScript で作成できるのは、TypeScript の Commerce 設定向けに init がスキャフォールディングする TypeScript ビルド設定（webpack-config.cjs とルートの tsconfig.json）がプロジェクトにある場合のみです。詳細は commerce-app-init を参照してください。それ以外の場合は、JavaScript でアクションを作成してください。

Step 1 — 意図の把握

何をどのようにインターセプトするか、ユーザーに確認してください。

• 操作：webhook_method（Commerce 操作。例：plugin.magento.catalog_product.save）と webhook_type（before または after）
• ハンドラーの呼び出し方法：このアプリのランタイムアクション（runtimeAction: "<package>/<action>"）または明示的な外部 URL（webhook.url）のいずれか。これらは相互に排他的です。
• カテゴリ（任意）：validation（無効な場合にブロック）、append（データを追加）、modification（データを変更）のいずれか。競合検出に使用します。
• バッチとフックの識別子：batch_name は関連するフックをグループ化し、hook_name はバッチ内でこのフックを一意に識別します。

Step 2 — 設定値の導出

書き込む前に、以下の検証ルールを適用してください。問題があれば、続行する前にユーザーに伝えてください。

フィールド	制約
batch_name	[a-zA-Z0-9_]+ のみ。ハイフン、ピリオド、スペースは不可
hook_name	[a-zA-Z0-9_]+ のみ。ハイフン、ピリオド、スペースは不可
category	任意。validation、append、modification のいずれか
runtimeAction	<package>/<action> 形式。webhook.url とは相互に排他的
webhook.url	有効な絶対 URL（https://...）であること。runtimeAction とは相互に排他的
label	必須。空でないこと
description	必須。空でないこと
webhook_type	必須。before または after であること
method	必須。POST、PUT、DELETE、GET のいずれかであること
timeout / soft_timeout	任意。正の整数（ミリ秒）
priority / batch_order	任意。正の整数

ステップ 3 — app.commerce.config.ts を更新する

トップレベルの webhooks 配列にエントリーを追加するか、配列がない場合は作成します。他のドメインはすべてそのまま残してください。設定にすでに webhooks キーがある場合は、置き換えずにエントリーを追加します。

最小限の例：

// Runtime action handler (handler lives in this app)
webhooks: [
  {
    label: "Validate Product Save",
    description: "Validates product data before saving.",
    category: "validation", // optional
    runtimeAction: "my-package/validate-product", // <package>/<action>
    webhook: {
      webhook_method: "plugin.magento.catalog_product.save",
      webhook_type: "before",
      batch_name: "my_app", // [a-zA-Z0-9_]+ only
      hook_name: "validate_product", // [a-zA-Z0-9_]+ only
      method: "POST",
    },
  },
];

// URL handler (external endpoint)
webhooks: [
  {
    label: "Fraud Check",
    description: "Calls external fraud service before order placement.",
    webhook: {
      webhook_method: "plugin.magento.sales_order.place",
      webhook_type: "before",
      batch_name: "my_app",
      hook_name: "fraud_check",
      method: "POST",
      url: "https://fraud.example.com/check", // inside webhook object, not top level
    },
  },
];

各エントリーでは、Commerce の特定の環境に適用範囲を限定するための任意の env 配列（"paas" ／ "saas"）も指定できます。省略した場合、Webhook はすべての環境に適用されます。指定した場合、インストール時にリストされた環境でのみ登録されます。

注釈付きの完全なリファレンスについては、assets/webhooks-config.ts を参照してください。

ハンドラーアクションの作成

runtimeAction を使用する Webhook エントリーの場合は、アクションファイルを src/actions/ の下に作成し、app.config.yaml に登録します。

アクションを登録する

既存の app-management パッケージと並べて、src/commerce-extensibility-1/ext.config.yaml にユーザー定義パッケージを追加します。フレームワークで予約されている app-management 以外の名前を使用してください。

# src/commerce-extensibility-1/ext.config.yaml
# (add below the auto-generated app-management package)
runtimeManifest:
  packages:
    app-management:
      # ... auto-generated — do not edit
    my-app: # your package name — any name except "app-management"
      actions:
        validate-product:
          function: actions/validate-product/index.js # relative to src/commerce-extensibility-1/
          web: "yes"
          runtime: nodejs:24
          annotations:
            require-adobe-auth: true

runtimeAction の <package>/<action> 形式は、直接対応します。my-app/validate-product → パッケージ my-app、アクション validate-product です。

ハンドラーの基本構成

// src/commerce-extensibility-1/actions/validate-product/index.ts
import {
  ok,
  successOperation,
  exceptionOperation,
  addOperation,
  replaceOperation,
  removeOperation,
} from "@adobe/aio-commerce-lib-webhooks/responses";

export async function main(params: Record<string, unknown>) {
  // params contains the Commerce operation payload

  // Allow the operation to proceed
  return ok(successOperation());

  // Block the operation (validation failure)
  // return ok(exceptionOperation("Product SKU is required"));

  // Append data to the operation result
  // return ok(addOperation("result/custom_field", { value: "appended" }));

  // Modify a field in the result
  // return ok(replaceOperation("result/price", 99.99));

  // Remove a field from the result
  // return ok(removeOperation("result/unwanted_field"));
}

操作の種類：

応答	効果
successOperation()	許可 — 操作は変更されずに続行されます
exceptionOperation(message)	ブロック — 操作はこのメッセージとともに拒否されます
addOperation(path, value)	結果の path にデータを追加します
replaceOperation(path, value)	結果の path の値を置き換えます
removeOperation(path)	結果から path のフィールドを削除します

ステップ 4 — installation アクションを再生成する

設定内で、webhooks がインストールを必要とする最初のドメインの場合（その他は eventing.commerce、eventing.external、adminUi、installation.customInstallationSteps です）、次を再実行します。

npx @adobe/aio-commerce-lib-app init

これにより、ext.config.yaml の app-management パッケージに installation アクションが追加されます。aio app build／aio app deploy は既存のファイルを読み取るだけで、再生成はしません。この手順を省略すると、Commerce に呼び出し可能なエンドポイントがなくなるため、Webhook は正常にビルドおよびデプロイされても、実際にはインストールされません。アクションがすでに存在する場合でも、安全に再実行できます。

ステップ 5 — 検証する

プロジェクトをビルドして、更新した設定が有効であることを確認します。

aio app build

検証エラーによるビルド失敗では、問題のある設定フィールドが直接示されます。この Webhook でステップ 4 が必要だった場合は、app-management の下に actions.installation が追加されていることも ext.config.yaml で確認してください。

よくある問題

• batch_name または hook_name が拒否される：区切り文字にはアンダースコアを使用してください（my_app、validate_product_save）。ハイフン、ドット、スペースは使用できません。
• runtimeAction と webhook.url の両方が設定されている：これらは相互排他です。ハンドラーがこのアプリ内にある場合は runtimeAction を、外部エンドポイントの場合は webhook.url を使用してください。
• url の階層が誤っている：URL を使用するエントリーでは、url はトップレベルで label と並べるのではなく、ネストされた webhook オブジェクト内に指定する必要があります。
• app-management パッケージ名の競合：フレームワークはビルドのたびに ext.config.yaml にこのパッケージを生成します。独自のアクションには、ほかの名前を使用してください。
• 関数のパスは src/commerce-extensibility-1/ からの相対パスです：src/... やプロジェクトルートからの相対パスは使用しないでください。actions/validate-product/index.js は正しく解決されますが、src/commerce-extensibility-1/actions/validate-product/index.js は解決されません。
• defineConfig が見つからない：@adobe/aio-commerce-lib-app がインストールされていることを確認し、@adobe/aio-commerce-lib-app/config から defineConfig をインポートしてください。
• Webhook はデプロイされたが、Commerce から呼び出されない：インストールを必要とする最初のドメインを追加した後に init が再実行されていません（ステップ 4）。installation アクションがないため、インストール用エンドポイントもありません。

品質基準

• aio app build がエラーなしで完了する
• この Webhook で必要な場合は、ext.config.yaml に installation アクションが含まれている

連携

aio app build が成功したら、次の操作を行います。

• マーチャント設定を追加する — commerce-app-business-config を呼び出し、Commerce Admin で設定可能な項目を公開します
• イベントサブスクリプションを追加する — commerce-app-eventing を呼び出し、Commerce または外部のイベントをサブスクライブします
• Admin UI を拡張する — commerce-app-admin-ui を呼び出し、Commerce Admin にカスタム列、一括操作、注文ビューのボタン、またはメニュー項目を追加します
• 永続ストレージを追加する — commerce-app-storage を呼び出し、クエリ可能な DB ストレージを Webhook ハンドラーのバックエンドとして使用します

参考資料

• assets/webhooks-config.ts — ランタイムアクションと URL ベースの Webhook エントリーの両方の形式を示す設定例