/commerce-app-webhooks

name: commerce-app-webhooks
description: >
  Add or modify webhook interceptors in an Adobe Commerce app. Use when the
  user wants to intercept Commerce operations to validate input, append data,
  or modify behavior — before or after execution. Requires a base app
  initialized with commerce-app-init.
license: Apache-2.0
compatibility: >
  Requires Node.js 22+, aio CLI, and @adobe/aio-commerce-lib-app.
  Requires a base app initialized with commerce-app-init.
metadata:
  author: adobe

Configure Commerce App Webhooks

Adds or modifies webhook interceptors in an existing `app.commerce.config.ts`. Webhooks intercept Commerce operations — you can validate input, append data, or modify behavior before or after an operation executes. Other extensibility domains (events, business config) are added separately via their own skills.

Prerequisites

• Verify the app is **scaffolded and initialized**, not merely that the config exists. Require **both**:
• `app.commerce.config.ts` present in the project root, **and**
• the project initialized — signalled by the generated `src/commerce-extensibility-1/` directory and installed `node_modules` (the `@adobe/aio-commerce-lib-app` dependency).
• If `app.commerce.config.ts` is **missing**, stop and invoke `commerce-app-init` first (it writes the config, then runs init).
• If the config is **present but the project is not initialized** (no `src/commerce-extensibility-1/` or `node_modules`), run `npx @adobe/aio-commerce-lib-app init` before continuing. Init is idempotent — it finds the existing config, skips the interactive prompts, installs dependencies, and generates the project files.
• Actions can be authored in TypeScript only once the project has the TypeScript build setup (`webpack-config.cjs` + root `tsconfig.json`) that `init` scaffolds for a TypeScript Commerce config — see `commerce-app-init`. Otherwise, author actions in JavaScript.

Step 1 — Understand intent

Ask the user what they want to intercept and how:

• **What operation**: the `webhook_method` (the Commerce operation, e.g., `plugin.magento.catalog_product.save`) and `webhook_type` (`before` or `after`)
• **How the handler is reached**: either a **runtime action** in this app (`runtimeAction: "<package>/<action>"`) or an **explicit external URL** (`webhook.url`) — these are mutually exclusive
• **Category** (optional): `validation` (block if invalid), `append` (add data), or `modification` (alter data) — used for conflict detection
• **Batch and hook identifiers**: `batch_name` groups related hooks; `hook_name` uniquely identifies this hook within the batch

Step 2 — Derive config values

Apply the following validation rules before writing. Surface any issues to the user before proceeding.

| Field | Constraint | | -------------------------- | ------------------------------------------------------------------------------------- | | `batch_name` | `[a-zA-Z0-9_]+` only — no hyphens, dots, or spaces | | `hook_name` | `[a-zA-Z0-9_]+` only — no hyphens, dots, or spaces | | `category` | Optional; must be `validation`, `append`, or `modification` | | `runtimeAction` | `<package>/<action>` format; mutually exclusive with `webhook.url` | | `webhook.url` | Must be a valid absolute URL (`https://...`); mutually exclusive with `runtimeAction` | | `label` | Required, non-empty | | `description` | Required, non-empty | | `method` | Required HTTP method (e.g., `POST`) | | `timeout` / `soft_timeout` | Optional; positive integer (milliseconds) | | `priority` / `batch_order` | Optional; positive integer |

Step 3 — Update `app.commerce.config.ts`

Add entries to the top-level `webhooks` array (or create it), preserving all other domains. If the config already has a `webhooks` key, append to it rather than replacing it.

Minimal examples:

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

Each entry also accepts an optional `env` array (`"paas"` / `"saas"`) to scope it to specific Commerce environments. When omitted, the webhook applies to all environments; when set, it is only subscribed at install time on the listed environments.

See [assets/webhooks-config.ts](assets/webhooks-config.ts) for the full annotated reference.

Creating the handler action

For webhook entries that use `runtimeAction`, create the action file under `src/actions/` and register it in `app.config.yaml`.

Register the action

Add a user-defined package to `src/commerce-extensibility-1/e