commerce-app-webhooks

配置 Commerce 应用 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（该命令会写入配置，然后运行 init）。
• 如果配置文件存在但项目尚未初始化（缺少 src/commerce-extensibility-1/ 或 node_modules），请先运行 npx @adobe/aio-commerce-lib-app init，然后再继续。init 操作是幂等的：它会找到现有配置，跳过交互式提示，安装依赖并生成项目文件。
• 只有在项目具备 TypeScript 构建设置（webpack-config.cjs + 根目录下的 tsconfig.json）后，才能使用 TypeScript 编写操作；init 会为 TypeScript Commerce 配置搭建这些设置 — 请参阅 commerce-app-init。否则，请使用 JavaScript 编写操作。

步骤 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 用于在批次内唯一标识此钩子

步骤 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
    },
  },
];

每个条目还可以接受一个可选的 env 数组（"paas" / "saas"），用于将其限定到特定的 Commerce 环境。省略时，webhook 适用于所有环境；设置后，仅会在列出的环境中于安装时订阅。

完整的注释参考请参阅 assets/webhooks-config.ts。

创建处理程序操作

对于使用 runtimeAction 的 webhook 条目，请在 src/actions/ 下创建操作文件，并在 app.config.yaml 中注册。

注册操作

在 src/commerce-extensibility-1/ext.config.yaml 中，与现有的 app-management package 一起添加一个用户定义的 package。名称可任意选择，但不能使用 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 → package my-app，action 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

此操作会将 installation 操作添加到 ext.config.yaml 的 app-management package 中 — aio app build/aio app deploy 只会读取现有文件，不会重新生成该文件。跳过此步骤后，Commerce 将没有可调用的端点，因此 webhook 虽然可以成功构建和部署，但实际上永远不会安装。即使该操作已存在，也可以安全地重新运行。

步骤 5 — 验证

构建项目，以确认更新后的配置有效：

aio app build

构建失败并出现验证错误时，会直接指出有问题的配置字段。如果此 webhook 需要执行步骤 4，也请检查 ext.config.yaml 中 app-management 下现在是否有 actions.installation。

常见问题

• batch_name 或 hook_name 被拒绝：使用下划线作为分隔符（my_app、validate_product_save）——不接受连字符、句点和空格。
• 同时设置了 runtimeAction 和 webhook.url：两者互斥 — 处理程序位于此应用中时使用 runtimeAction；外部端点则使用 webhook.url。
• url 位于错误的层级：对于基于 URL 的条目，url 必须位于嵌套的 webhook 对象内，而不能与 label 一起放在顶层。
• app-management package 名称冲突：框架会在每次构建时于 ext.config.yaml 中生成此 package。请为自己的操作使用其他名称。
• 函数路径相对于 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，并且 defineConfig 是从 @adobe/aio-commerce-lib-app/config 导入的。
• webhook 已部署，但 Commerce 从未调用它：添加第一个需要安装的域后没有重新运行 init（步骤 4）——没有 installation 操作，就没有安装端点。

质量标准

• aio app build 完成且无错误
• 如果此 webhook 需要 installation 操作，则该操作必须出现在 ext.config.yaml 中

链接后续操作

aio app build 通过后：

• 添加商家设置 — 调用 commerce-app-business-config，在 Commerce Admin 中提供可配置的设置
• 添加事件订阅 — 调用 commerce-app-eventing，订阅 Commerce 或外部事件
• 扩展 Admin UI — 调用 commerce-app-admin-ui，在 Commerce Admin 中添加自定义列、批量操作、订单视图按钮或菜单项
• 添加持久化存储 — 调用 commerce-app-storage，为 webhook 处理程序提供支持可查询的数据库存储

参考资料

• assets/webhooks-config.ts — 参考配置，展示运行时操作和基于 URL 的 webhook 条目结构