Out-of-Process Extensibility

Adobe I/O Events for Adobe Commerce requires Adobe Commerce 2.4.4 or later; Magento Open Source is not supported, and bin/magento module:status on Mage-OS 3.6.0 lists no Magento_AdobeCommerceEventsClient. On PaaS the modules come with Commerce from 2.4.6 and are loaded automatically; on 2.4.4 and 2.4.5 they are installed with composer require magento/commerce-eventing=^1.0 --no-update. The four modules are Magento_AdobeCommerceEventsClient, Magento_AdobeCommerceEventsGenerator, Magento_AdobeIoEventsClient and Magento_AdobeCommerceOutOfProcessExtensibility. On premises the installation ends with a generated module (events are delivered through plugins and observers that are generated from the list of subscribed events):

Source: Adobe Commerce docs: Install Adobe I/O Events for Adobe Commerce

On Adobe Commerce on cloud infrastructure the same installation needs the app/etc/config.php file in the repository, an ece-tools version of 2002.1.13 or later and ENABLE_EVENTING: true in the global stage of .magento.env.yaml; the generated module is produced by the deployment. Updates are composer update magento/commerce-eventing --with-dependencies followed, on premises, by setup:upgrade, cache:clean and setup:di:compile. Events also need a working cron (a system crontab that runs bin/magento cron:run): the cron job event_data_batch_send transmits the stored events in batches and clean_event_data removes old ones, both in the default cron group. Events marked as priority are handled by the message queue consumer commerce.eventing.event.publish, which processes them within a second, while standard events wait for the cron (up to 59 seconds). On cloud infrastructure the consumer runs through CRON_CONSUMERS_RUNNER in the deploy stage.

The connection has four parts, all documented on one page. In the Developer Console, create a project and a workspace, add the services I/O Management API, I/O Events and I/O Events for Adobe Commerce, and download the workspace configuration file (<workspace-name>.json). In the Admin, under Stores > Settings > Configuration > Adobe Services > Adobe I/O Events > General configuration, paste that file into Adobe I/O Workspace Configuration, enter a unique Adobe I/O Event Provider Instance ID (alphanumeric characters, hyphens and underscores) and save. Then create the event provider, either with the Create Event Provider button or with the command below, and copy the returned id into the Adobe I/O Event Provider ID field:

Finally enable eventing (Commerce Eventing > Enabled), set Merchant ID and Environment ID (they are joined into the source attribute of every event, <merchant-id>.<environment-id>, so that one provider can serve several environments), optionally change Maximum retries to send events (default 7) and Event retention time (in days) (default 3; a cron job named clean_event_data deletes older event data every 24 hours), save, and press Send Test Event. The provider appears in the Developer Console only after an event has been subscribed; create the event registration there (Add service, Event, Commerce events), choose the provider, tick the events and choose how the registration receives them.

Source: Adobe Commerce docs: Configure Adobe Commerce for events

Source: Adobe Commerce docs: Event management commands

An event code is <type>.<name>: observer.<event name> for an event dispatched with the Commerce event manager (for example observer.sales_order_place_after) and plugin.<class path>.<method> for a plugin on a method or an API interface (for example plugin.magento.sales.api.order_management.place, the class path in lower case with . for \). Observer events are the default; a plugin event needs the extra generation and compilation step above. The list of events that exist is large (Adobe states that Commerce can emit thousands) and most are not good candidates; use System > Events > Events List in the Admin or bin/magento events:list:all to find them and events:info to see a payload.

An event can be fixed in a module, so that every installation of the module sends it. The file is etc/io_events.xml in a module, or app/etc/io_events.xml; <field name="*"/> selects every field (it cannot match part of a name), items[].sku selects a field inside each element of an array, and the converter attribute names a class that changes the value (for example an integer visibility into a string). Several modules that register the same event are merged; the transmitted event holds the union of the fields. The same subscription can be declared in the io_events section of app/etc/config.php, and since version 1.11.0 of the module also in app/etc/env.php.

Source: Adobe Commerce docs: Commerce module development for events; Adobe Commerce docs: Create conditional events

A conditional event (the second one above) extends a parent event: Commerce evaluates the rules against the parent payload and sends the conditional event only if every rule is true, which saves calls. The operators are greaterThan, lessThan, equal (use 1 and 0 for booleans), regex (with delimiters, for example /^TV .*/i), in (a comma-separated list) and onChange, which compares a field with its previous value and works only for events whose payload includes the original data (_origData). Rules may also use context fields (prefixed context_) such as the area code or the store id.

Two limits to design around. The payload of an event is limited to 64 KB; a larger event is not created, and that is the reason to send a few fields instead of everything (it also keeps sensitive and card data out of the event). And an event payload reflects the object at the moment of the event; the order event of Pocket Coffee carries the number, the total and the currency, and anything else (the lines, the customer) is read back with a REST callback when the action needs it.

A registration can deliver to four places: the Journaling API (the default; events are appended to an ordered list that your code reads with the Adobe I/O Events SDK), a webhook URL (forwarding to a third-party endpoint without App Builder), a runtime action (your function is invoked with the event) and Amazon EventBridge. A runtime action reads the event from params.data.value; the event type in params.type is com.adobe.commerce. followed by the event code.

Source: Adobe Commerce docs: Consume events

Because failed deliveries are retried, the same event can arrive more than once, so an action must be idempotent: the order number is the natural key, and the roastery’s system should ignore a second delivery of the same number. Adobe I/O Events retries a failed delivery by its own rules (see its documentation for retry and dead-letter behaviour); Commerce itself retries sending to Adobe I/O Events up to the configured maximum (7 by default).

On ACCS the subscriptions are made in the Admin (System > Events > Events Subscriptions, with an event name, an optional alias that rules require, the provider, Is Enabled and Priority) or with the REST API; only a predefined list of events is supported and more are requested through support.

Source: Adobe Commerce docs: Create event subscriptions from the Admin

A webhook is a synchronous subscription: when a Commerce event or plugin method runs, Commerce sends an HTTP request to your URL, waits for the answer and applies it. The answer decides the outcome: the process continues unchanged, it stops with an exception, or the arguments of the original call are changed. That makes webhooks the tool for validation (refuse an add to cart, an address, a discount code), for computing something Commerce needs immediately (taxes, shipping rates, discounts, payment validation) and for enriching data (add a shipping method, fill a product description). Webhooks are documented for Adobe Commerce, PaaS and SaaS; the pages never state a Magento Open Source rule, and the module is not part of Mage-OS 3.6.0.

A webhook method is named like an event, <type>.<name> where the type is observer or plugin, and runs before or after the original action (an around plugin is not supported). The pair method name plus type must be unique across the system.

On cloud infrastructure ENABLE_WEBHOOKS: true goes into .magento.env.yaml (ece-tools 2002.1.16 or later) and the generation happens at deployment. The generated module contains one plugin or observer per subscribed method; after adding a hook for a new method, regenerate and compile.

Source: Adobe Commerce docs: Install Adobe Commerce Webhooks

On PaaS the subscription is a webhooks.xml file in the etc directory of a module or in app/etc. On SaaS the same properties are entered in System > Webhooks > Webhooks Subscriptions or sent to the REST API, and the methods that exist are listed in System > Webhooks > Webhooks List or by GET /V1/webhooks/supportedList. The structure is config > method > hooks > batch > hook, with headers, fields and rules inside a hook.

Source: Adobe Commerce docs: Webhooks configuration reference; Adobe Commerce docs: Create a webhook

The context values are a feature worth knowing: a field or a header can take its value from the application context instead of the event payload, with a source such as context_customer_session.get_customer.get_email, context_store.get_store.get_id, context_scope_config.get_value{web/secure/base_url:default} (arguments in braces, separated by colons) or context_http_request.get_header{X-Custom-Header}. If the value cannot be read, the problem is logged and the hook still runs.

Here is the hook of Pocket Coffee’s parcel weight rule. It listens to plugin.magento.quote.api.cart_item_repository.save (the API that saves a cart line), sends only the SKU and the quantity under the names the endpoint expects, and runs only for coffee bags, whose SKU ends in the bag size.

Source: Adobe Commerce docs: Configure hook contents

The file is well-formed (checked with xmllint). It could not be validated against its schema, because the schema ships with the Adobe module, and the 2.4.8 to 2.4.9 backward-incompatible-changes list names webhooks.xsd and io_events.xsd among the XSD files removed in 2.4.9; the documentation still shows the xsi:noNamespaceSchemaLocation reference.

The endpoint must return HTTP 200 with a JSON object, or an array of objects, each with an op:

instance accepts only data object classes (extending DataObject or AbstractSimpleObject, or implementing ExtensibleDataInterface); on PaaS more classes can be allowed through the allowedTypes argument of InstanceValidator in di.xml. Failures are logged as follows: a 2xx answer within the limits logs nothing; an optional hook that returns another status or times out logs an error; a required hook does the same and throws; exceeding the soft timeout adds a notice. On PaaS the log is var/log/system.log; database logging (Stores > Configuration > Adobe Services > Webhooks > Database logging configuration, table webhook_log, grid System > Webhooks > Webhook Logs) is for debugging and must be off in production.

Source: Adobe Commerce docs: Webhook responses and logging

A webhook URL is public, so the endpoint must authenticate the caller. There are three mechanisms: the OAuth credential (developerConsoleOauth, which makes Commerce send an IMS bearer token that Runtime can validate with require-adobe-auth), a header you define (a shared secret kept in an environment variable), and signature verification. The signature is off by default: enable it under Stores > Settings > Configuration > Adobe Services > Webhooks and press Regenerate key pair; Commerce then adds the header x-adobe-commerce-webhook-signature. The value is the base64 of an RSA SHA-256 signature (the documentation calls it an HMAC in the text, and its code verifies with crypto.createVerify('SHA256') and the public key) computed over the base64 encoding of the request body. Regenerating the pair invalidates the old public key.

The validate-stock action of Pocket Coffee does that check first, and is the endpoint behind the hook above. It runs as a raw-http action, so the body arrives as params.__ow_body, already base64 encoded, which is exactly what was signed.

Source: Adobe Commerce docs: Webhooks signature verification

Neither the Adobe webhooks module nor Adobe Developer Console was available, so the exchange was reproduced in two parts that can be run on any machine. The actions run under a thirty-line stand-in for Runtime (local-runtime.js below), which calls main(params) the way a raw-http web action is called. On Mage-OS 3.6.0 a module named PocketCoffee_OopeBridge registers a before plugin on Magento\Quote\Api\CartItemRepositoryInterface::save that builds the request of the hook above (the fields mapping, a 2000 ms timeout, an optional hook), signs the body with a private key and applies the exception operation, and an observer on sales_order_place_after that posts the order event. It is the contract, not the product: no queue, no cron, no retries, no add, replace or remove.

Source: App Builder docs: Securing web actions

Source: Adobe Commerce docs: Plugins (interceptors)

Source: Adobe Commerce docs: Webhooks signature verification

The observer for the event has the same shape (it posts increment_id, grand_total and order_currency_code to the order-placed action) and is registered in etc/events.xml; the plugin in etc/di.xml.

Source: Adobe Commerce docs: Dependency injection

With the module enabled and the local runtime listening, a guest cart on the Spanish store view accepts four 1 kg bags and refuses six. The SKUs are the variants of the beans product built in Catalog, Multistore and B2B; they carry the prefix PCMS- and end with the bag size, which is what the weight rule reads:

Source: Adobe Commerce docs: Create a webhook

The action’s log line was blocked 6 x PCMS-ETH-WHL-1KG: 6 kg is over 5 kg. A guest checkout that placed an order afterwards produced order placed 2000000001 total 24.7 EUR in the log of the order-placed action. The two behaviours that the emulation shares with the real hook are the ones that matter in practice: the shopper sees the message the endpoint chose, and a missing or invalid signature is answered with an exception, because the first check of the action is the signature. (If the local runtime is down the emulated hook is optional, like required="false", and the cart still works; with required="true" a real hook would stop every add to cart of coffee, which is the main operational risk of a required webhook.)

Source: Adobe Commerce docs: Test webhooks

On a real PaaS installation bin/magento webhooks:dev:run observer.checkout_cart_product_add_before:before '<json>' runs a registered hook with a payload you give it, filtered by the hook’s fields, without triggering the original action; webhooks:list lists the registered hooks, webhooks:list:all the methods that can be subscribed and webhooks:info <name> [--webhook-type] [--depth] shows the payload of a method (the real payload can differ from the one shown, because the command builds it from the current state of the objects).

Source: Adobe Commerce docs: Webhooks commands

An Admin page used to be a PHP module: menu.xml, acl.xml, a controller, a UI component grid or form (see Admin Development). The Admin UI SDK keeps the Admin as the shell and moves the content out. Two components make it work: CommerceBackendUix, a small in-process PHP module that lets the Admin inject menus, grid columns, mass actions and buttons, and a React application (web-src) in your App Builder project that renders the page inside an iframe. Adobe Identity Management Service (IMS) authenticates the administrator; the merchant enters the IMS organisation in the Admin and the installation requires that the Admin signs in through Adobe IMS (on PaaS, see Configure the Commerce Admin Integration with Adobe ID), which also disables the native two-factor authentication module. The SDK is installed automatically with Adobe Commerce 2.4.8 and later, comes enabled on ACCS and is installed with Composer on 2.4.5 to 2.4.7. The installation page states that Magento Open Source is not supported.

Source: Adobe Commerce docs: Install or update the Admin UI SDK

The SDK is versioned. Version 5.0.0 (2026-09-16) added the invoice, credit memo and shipment grid column extension points to version 2 of the extension points and removed the V1 customFees extension point (order totals are changed by a webhook instead); 4.2.0 introduced the adminUi configuration of App Management for PaaS 2.4.8 and later and for ACCS; 3.3.0 or later is required for the App Management screen; 3.0 or later hands the IMS token to the iframe through the shared context. Version 1 of the extension points (commerce/backend-ui/1, registered by an ExtensionRegistration React component and a registration runtime action) is deprecated; version 2 (commerce/backend-ui/2) is declared in the adminUi block of app.commerce.config, with no registration component or action to write. Under Stores > Settings > Configuration > Adobe Services > Admin UI SDK the SDK is disabled until Enable Admin UI SDK is set to Yes, Refresh registrations reloads what the App Builder registry holds, and logging to the database (System > Admin UI SDK > Admin UI SDK Logs) is off by default.

Source: Adobe Commerce docs: Admin UI SDK release notes

Any menu item, mass action, view button or column can be put behind a dedicated ACL resource with aclProtected: true; Commerce then generates a nested resource for the app in the User Roles tree so that each administrator role can be granted individual items. Without it the item uses the shared resource Magento_CommerceBackendUix::adminuisdk_extensions. The iframe page reads its context with hooks from @adobe/aio-commerce-lib-admin-ui/web: useIms() (the administrator’s IMS token and organisation), useHostConnection() (close() and closeWithError() to go back to the grid), useMassActionContext() (selectedIds), useOrderViewButtonContext() (orderId), useCommerce() (the host) and useSharedContext(). A mass action that opens an iframe receives the selected ids, the Commerce base URL, the client id, the IMS token and the IMS organisation id in the shared context; a menu or order button receives the token and the organisation only.

Source: Adobe Commerce docs: Admin UI SDK extension points (V2)

The Pocket Coffee roast schedule needs one menu entry under Catalog and one worker mass action on the order grid that prints roast labels. Both live in app.commerce.config.ts, which is the next section’s file.

API Mesh for Adobe Developer App Builder is a hosted gateway. A mesh is a JSON configuration (meshConfig) that lists sources (each with a handler: graphql, openapi or JsonSchema) and optional transforms, and the service serves one GraphQL endpoint over all of them. It is the tool when a storefront or an app needs data from Commerce and from other systems in one request, when an old REST API has to look like GraphQL, or when the Commerce schema must be reshaped (names, fields, prefixes) without touching Commerce. It adds a cache, a web application firewall and distributed denial-of-service protection on Adobe’s edge, and the mesh is limited to 375 KB (750 KB when files are referenced through the files array). Each workspace of a Developer Console project can have one mesh.

The commands are api-mesh:init, run, create, update, status, get, delete, describe, source:discover, source:get, source:install (prebuilt source configurations) and the log commands (log-list, log-get, log-get-bulk). Source names may contain only letters and digits, the file uploaded to create must end in .json, and header names are lower cased. A mesh endpoint is used with an API key or, for the edge URL, the headers you forward. The local server started by api-mesh:run was used for the example below.

Source: API Mesh docs: Create a mesh

The Pocket Coffee roastery keeps the roast date and batch of each SKU in its own small REST service. The mesh below joins the Commerce GraphQL endpoint (forwarding the Store header of the caller, so that the Spanish storefront gets Spanish names) and the roastery’s OpenAPI description (roastery-openapi.json, referenced directly, which is allowed for .json and .js files whose path is shorter than 25 characters and in the same directory). The prefix transform with includeRootOperations keeps the roastery’s operation names from colliding with Commerce’s.

Source: API Mesh docs: Source handlers; API Mesh docs: Transforms

Source: API Mesh docs: Developer tools

The mesh ran locally with aio api-mesh:run mesh.json -p 5050 (port 5000, the default, belongs to the macOS AirPlay receiver and answers 403) against the Mage-OS GraphQL endpoint and the roastery stub, and one query answered from both sources:

Source: API Mesh docs: Create a mesh

Source: API Mesh docs: Work with your mesh

Practical notes from running it. The handler package versions the service supports are old (graphql 0.34.13, openapi 0.33.39, JsonSchema 0.35.38 in the documentation), so a schema feature newer than those may not be understood. The build needs TypeScript 5: with TypeScript 6 in the project the schema generation failed with error TS5107 (a deprecated moduleResolution), and the project of @adobe/aio-commerce-lib-app needs TypeScript 6 for its web-src scaffold, so the two tools belong in separate directories. When the local build fails once, it leaves its artefacts (mesh-artifact, meshes, tempfiles, testMesh) in the working directory; delete them before the next attempt, or the failed introspection can be reused. For ACCS the documented source uses the single Commerce GraphQL URL with the headers Magento-Environment-Id, Magento-Store-View-Code, Magento-Website-Code, Magento-Store-Code and X-Api-Key, plus schemaHeaders for the introspection.

Source: API Mesh docs: Adobe Commerce as a Cloud Service best practices