Skip to main content
skill CX Codex

commerce-app-webhooks — Claude Code skill

The commerce-app-webhooks skill adds webhook interceptors to an Adobe Commerce app. Validate input data, append information, or modify operation behavior before or after execution.

Apache-2.0 330 installs ★ 335 updated 2026-11-14

Install into Claude Code · Skills CLI (Vercel) All methods and platforms ↓
npx skills add adobe/skills --skill commerce-app-webhooks -a claude-code
Open on GitHub

What commerce-app-webhooks does

The skill modifies app.commerce.config.ts and extends the webhooks array. Each interceptor binds to a Commerce operation (such as plugin.magento.catalog_product.save) and fires before or after it runs. The handler either lives in the app as a runtime action in a package like my-app/validate-product, or points to an external URL.

Before adding a webhook, the skill verifies the project is initialized: both app.commerce.config.ts and the directory src/commerce-extensibility-1/ must exist, along with installed node_modules. If the config is present but the project is not yet initialized, the skill runs npx @adobe/aio-commerce-lib-app init.

Each webhook requires the operation name, type (before or after), category (validation, append, or modification), and batch and hook names (alphanumeric and underscore only). For runtime-action handlers, the skill creates an action file under src/actions/ and registers it in src/commerce-extensibility-1/ext.config.yaml.

What it helps with

  • validate product data before it is saved to the catalog
  • intercept order placement and forward data to a third-party service
  • append computed fields to an operation before it executes
  • prevent an operation if validation fails
  • track and log all changes within Commerce

Example prompts for the agent

  • Add a webhook that validates product price before save
  • Create an interceptor to check orders for fraud before they are placed
  • Set up a webhook to append metadata to products on save

How to install commerce-app-webhooks

1Skills CLI (Vercel)

npx skills add adobe/skills --skill commerce-app-webhooks -a claude-code

2Manually: put the files in place

~/.claude/skills/commerce-app-webhooks/SKILL.md

Copy the whole skill folder; for one project use .claude/skills/commerce-app-webhooks/

Step by step, with commands for each platform: How to install skills in Claude Code: five ways

Questions about commerce-app-webhooks

How do I install commerce-app-webhooks in Claude Code?

Run npx skills add adobe/skills --skill commerce-app-webhooks -a claude-code, then open ~/.claude/skills/commerce-app-webhooks/SKILL.md.

What is a webhook and why would I use it?

A webhook is an interceptor that fires on a Commerce operation before or after it executes. Use it to validate data, add fields, or change how an operation behaves.

What are the requirements for this skill?

You need Node.js 22+, aio CLI, and @adobe/aio-commerce-lib-app. The app must be initialized with the commerce-app-init skill, which creates app.commerce.config.ts and the src/commerce-extensibility-1/ directory.

Source text

SKILL.md · Apache-2.0
---
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                                                                   |
| `webhook_type`             | Required; must be `before` or `after`                                                 |
| `method`                   | Required; must be `POST`, `PUT`, `DELETE`, or `GET`                                   |
| `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:

```ts
// 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/ext.config.yaml` alongside the existing `app-management` package. Use any name except `app-management` (reserved by the framework):

```yaml
# 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:26
          annotations:
            require-adobe-auth: true
```

The `<package>/<action>` format in `runtimeAction` maps directly: `my-app/validate-product` → package `my-app`, action `validate-product`.

### Handler skeleton

```typescript
// 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"));
}
```

Operation types:

| Response                        | Effect                                          |
| ------------------------------- | ----------------------------------------------- |
| `successOperation()`            | Allow — operation proceeds unchanged            |
| `exceptionOperation(message)`   | Block — operation is rejected with this message |
| `addOperation(path, value)`     | Append data at `path` in the result             |
| `replaceOperation(path, value)` | Replace the value at `path` in the result       |
| `removeOperation(path)`         | Remove the field at `path` from the result      |

## Step 4 — Regenerate the `installation` action

If `webhooks` is the first install-requiring domain in the config (the others are `eventing.commerce`, `eventing.external`, `adminUi`, `installation.customInstallationSteps`), re-run:

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

This is what adds the `installation` action to `ext.config.yaml`'s `app-management` package — `aio app build`/`aio app deploy` only read the existing file, they never regenerate it. Skip this and Commerce has no endpoint to call, so the webhook builds and deploys fine but never actually gets installed. Safe to re-run even when the action already exists.

## Step 5 — Validate

Build the project to confirm the updated config is valid:

```sh
aio app build
```

A build failure with a validation error points directly to the offending config field. If this webhook needed Step 4, also check that `ext.config.yaml` now has `actions.installation` under `app-management`.

## Common Issues

- **`batch_name` or `hook_name` rejected**: Use underscores as separators (`my_app`, `validate_product_save`) — hyphens, dots, and spaces are not accepted.
- **Both `runtimeAction` and `webhook.url` set**: These are mutually exclusive — use `runtimeAction` when the handler lives in this app; `webhook.url` for an external endpoint.
- **`url` at wrong level**: For URL-based entries, `url` must be inside the nested `webhook` object, not at the top level alongside `label`.
- **`app-management` package name conflict**: The framework generates this package in `ext.config.yaml` on every build. Use any other name for your own actions.
- **Function path is relative to `src/commerce-extensibility-1/`**: Do not use `src/...` or project-root-relative paths. `actions/validate-product/index.js` resolves correctly; `src/commerce-extensibility-1/actions/validate-product/index.js` does not.
- **`defineConfig` not found**: Ensure `@adobe/aio-commerce-lib-app` is installed and `defineConfig` is imported from `@adobe/aio-commerce-lib-app/config`.
- **Webhook deployed but Commerce never calls it**: `init` wasn't re-run after adding the first install-requiring domain (Step 4) — no `installation` action, no install endpoint.

## Quality Bar

- `aio app build` completes without errors
- `installation` action present in `ext.config.yaml` when this webhook requires it

## Chaining

After `aio app build` passes:

- **Add merchant settings** — invoke `commerce-app-business-config` to expose configurable settings in Commerce Admin
- **Add event subscriptions** — invoke `commerce-app-eventing` to subscribe to Commerce or external events
- **Extend the Admin UI** — invoke `commerce-app-admin-ui` to add custom columns, mass actions, order view buttons, or menu entries in Commerce Admin
- **Add persistent storage** — invoke `commerce-app-storage` to back webhook handlers with queryable DB storage

## References

- [assets/webhooks-config.ts](assets/webhooks-config.ts) — Reference config showing both runtime action and URL-based webhook entry shapes

© adobe · Apache-2.0 · adobe/skills

Similar skills

All skills for Backend and APIs →

From the same set108

The whole set →
commerce-app-business-config commerce-app-business-config adds typed business configuration fields to an Adobe Commerce app through businessConfig.schema. Merchants set them in Commerce Admin, the app reads values at runtime. CX Codex +1 334installs link-rot-scanner link-rot-scanner is a Claude Code skill that finds and validates internal and external links on AEM Edge Delivery Services sites. Run it before launch or after content migration. CX Codex +1 334installs commerce-app-eventing commerce-app-eventing configures Commerce and external event subscriptions, extraction rules, and runtime action handlers in Adobe Commerce apps. CX Codex +1 332installs commerce-app-storage commerce-app-storage — a skill for Claude Code, Cursor, Codex and other platforms that wires App Builder Database Storage into an existing Adobe Commerce app and scaffolds a runtime action for reading and writing documents. CX Codex +1 331installs rollout rollout deploys a whole migrated site to AEM Edge Delivery Services in one run. Inventories the page tree, deduplicates blocks, drives deploy per page, and tracks what's done and what's left. CX Codex +1 318installs adobe-edit-quick-cut adobe-edit-quick-cut turns a video into one highlight cut by selecting relevant moments. Use it for a teaser, sizzle reel, or visual summary. CX Codex +1 308installs cwv-optimizer cwv-optimizer diagnoses Core Web Vitals bottlenecks on AEM Edge Delivery Services sites and offers targeted fixes with score projections. CX Codex +1 306installs adobe-resize-photos-and-videos adobe-resize-photos-and-videos scales photos and videos to explicit pixel sizes or aspect ratios via Adobe tools. Useful when prepping files for web display, print, or video channels. CX Codex +1 303installs

Project sponsors

Companies that keep this analytics open