# mage-os/mageos-async-events > An event-driven flexible async events module that allows you to process any event asynchronously. `composer require mage-os/mageos-async-events` Canonical URL: https://packagento.com/mage-os/mageos-async-events ## At a glance - **Vendor**: mage-os (https://packagento.com/mage-os.md) - **Latest version**: v4.0.8 — released 2026-07-08 - **Pricing**: Free - **Package type**: Magento 2 module - **Status**: active, accepting new buyers ## Installation Packagento is licence-gated, so even free packages need a licence on a project before Composer can resolve them. 1. **Sign in or create an account** at https://packagento.com/customer/account/. 2. **Add the package to your account.** Open https://packagento.com/mage-os/mageos-async-events and complete the free checkout. A licence is minted automatically. 3. **Create or pick a project, then activate the licence on it.** - Projects represent the Magento installs you deploy to. Manage them at https://packagento.com/projects/. - Activate the new licence on the project you'll deploy this package to. Activation is what generates the Composer credentials scoped to that project. 4. **Add the project credentials to your Magento codebase.** Grab the project's public + private key from https://packagento.com/projects/ (open the project, then its Credentials tab), and add them to `auth.json`: ```json { "http-basic": { "packagento.com": { "username": "ppk_live_...", "password": "psk_live_..." } } } ``` Add the Packagento Composer repository to `composer.json`: ```json { "repositories": [ { "type": "composer", "url": "https://packagento.com" } ] } ``` 5. **Install and apply.** ```bash composer require mage-os/mageos-async-events:* bin/magento setup:upgrade bin/magento setup:di:compile bin/magento cache:flush ``` ## What it does An event-driven flexible async events module that allows you to process any event asynchronously. ## README [![Integration Test](https://github.com/mage-os/mageos-async-events/actions/workflows/integration-tests.yml/badge.svg)](https://github.com/mage-os/mageos-async-events/actions/workflows/integration-tests.yml) [![REST](https://github.com/mage-os/mageos-async-events/actions/workflows/api-functional-tests.yml/badge.svg)](https://github.com/mage-os/mageos-async-events/actions/workflows/api-functional-tests.yml) A framework for reliably handling asynchronous events with Magento. * **Asynchronous**: The module uses RabbitMQ (or DB queues) to leverage asynchronous message delivery. * **Flexible**: Decoupling events and dispatches provide greater flexibility in message modelling. * **Scalable**: Handles back pressure and provides an asynchronous failover model automatically. ### Installation ```shell $ composer require mage-os/mageos-async-events ``` Install the module: ```shell $ bin/magento setup:upgrade ``` ### Usage #### Define an asynchronous event Create a new `async_events.xml` under a module's `etc/` directory. ```xml ``` #### Create a Subscription > [!TIP] > To view all available event sinks, check out [Async Event Sinks](https://github.com/mage-os/mageos-async-events-sinks) ##### HTTP ```shell curl --location --request POST 'https://test.mageos.dev/rest/V1/async_event' \ --header 'Authorization: Bearer TOKEN' \ --header 'Content-Type: application/json' \ --data-raw '{ "asyncEvent": { "event_name": "sales.order.created", "recipient_url": "https://example.com/order_created", "verification_token": "supersecret", "metadata": "http" } }' ``` ##### Amazon EventBridge Requires the [AWS Sinks](https://github.com/mage-os/mageos-async-events-aws) package ```shell curl --location --request POST 'https://test.mageos.dev/rest/V1/async_event' \ --header 'Authorization: Bearer TOKEN' \ --header 'Content-Type: application/json' \ --data-raw '{ "asyncEvent": { "event_name": "sales.order.created", "recipient_url": "arn:aws:events:ap-southeast-2:ACCOUNT_ID:rule/BUS_NAME", "verification_token": "supersecret", "metadata": "eventbridge" } }' ``` #### Dispatch an asynchronous event ```php use \MageOS\AsyncEvents\Model\AsyncEventPublisher; // ... public function __construct(private readonly AsyncEventPublisher $asyncEventPublisher) {} public function execute(Observer $observer): void { /** @var Order $order */ $order = $observer->getData('order'); // arguments are the inputs required by the service class in the asynchronous // event definition in async_events.xml // e.g: Magento\Sales\Api\OrderRepositoryInterface::get $message = ['id' => $order->getId()]; $this->asyncEventPublisher->publish('sales.order.created', $message); } ``` Ensure the following consumers are running ```shell bin/magento queue:consumer:start event.trigger.consumer bin/magento queue:consumer:start event.retry.consumer ``` ## Features ### Trace All events are logged at the individual subscription level with a UUID. All information from the first delivery attempt to the latest attempt is presented as a trace table. The event payload is also available to view for investigation purposes. ![Event Trace Page](docs/trace.png) ### Retries Events are automatically retried with quadratic back off. The default retry limit is 5. The maximum backoff is 60 seconds. > [!IMPORTANT] > RabbitMQ is required for retries with back off. If you are using DB queues then quadratic back off is > not available, and you will have to implement your own `\MageOS\AsyncEvents\Api\RetryManagementInterface` The quadratic backoff is calculated as `min(60, pow($deathCount, 2));` | Attempt | Backoff | |---------|------------| | 1 | 1 second | | 2 | 4 seconds | | 3 | 9 seconds | | 4 | 16 seconds | | 5 | 25 seconds | To change the default retry limit visit Admin > Stores > Settings > Configuration > Advanced > System > Async Events and update `Maximum Deaths`. ![Retry Limit Config Page](docs/retry_limit_config.png) ### Replays An event can be replayed independent of its status. This is useful to debug or replay an event when all retries are exhausted. Replays start a new chain of delivery attempts and will respect the same retry mechanism if they fail again. ### Lucene Query Syntax All events are indexed in Elasticsearch by default. This allows you to search through events including the event payload! The module supports [Lucene Query Syntax](https://lucene.apache.org/core/2_9_4/queryparsersyntax.html) to query event data like attributes. The following attributes are available across all asynchronous events. ``` log_id uuid event_name success created ``` The following attributes differ between asynchronous event types. ``` data ``` #### Examples Assuming you have the following events configured ``` customer.created customer.updated customer.deleted sales.order.created sales.invoice.created shipment.created shipment.updated shipment.deleted ``` You can query all customer events by using a wildcard like `event_name: customer.*` which matches the following events ``` customer.created customer.updated customer.deleted ``` You can query all created events like `*.created` which matches the following events ``` customer.created sales.order.created sales.invoice.created shipment.created ``` You can further narrow down using the other available attributes such as status or uuid. The following query returns all customer events which have failed. `customer.* AND success: false` _(README truncated for .md surface. Full README on https://packagento.com/mage-os/mageos-async-events.)_ ## Recent Versions | Version | Released | |---|---| | v4.0.8 | 2026-07-08 | | v4.0.7 | 2026-03-19 | | v4.0.6 | 2025-09-30 | | v4.0.5 | 2025-05-06 | | v4.0.4 | 2025-01-23 | | v4.0.3 | 2025-01-02 | | v4.0.2 | 2024-12-17 | | v4.0.1 | 2024-07-12 | | v4.0.0 | 2024-06-27 | | v4.0.0-beta | 2024-04-27 | Showing 10 of 13 versions. Full release history on https://packagento.com/mage-os/mageos-async-events. ## Dependencies ### Require | Package | Constraint | |---|---| | cloudevents/sdk-php | ^1.1 | | magento/framework | * | | php | >=8.1 | ### Require (dev) | Package | Constraint | |---|---| | magento/magento-coding-standard | * | | squizlabs/php_codesniffer | ~3.5 | ## Quality Latest release (v4.0.8) fails the Packagento QA pipeline. Verdicts below are per-cell (Magento line × PHP version) for the matrixed tools, and run-once for the static / security tiers. ### Compatibility Each Magento line is installed on its supported PHP versions, then the module is built (DI compile + static-content deploy). Cells show passed / failed / untested; staircase gaps render as `–`. | Magento | PHP 8.2 | PHP 8.3 | PHP 8.4 | PHP 8.5 | |---|---|---|---|---| | 2.4.7 | Pass | Pass | – | – | | 2.4.8 | – | Pass | Pass | – | | 2.4.9 | – | – | Pass | Pass | ### Code Quality Advisory checks against the module's source. Never affect the Compatibility verdict — a phpcs finding can't make a module incompatible. #### Static Analysis Coding standards (phpcs), mess detection (phpmd), copy-pasted code (cpd), PHP cross-version compatibility, composer.json validity. Each runs once for the whole module. | Tool | Status | Findings | Summary | |---|---|---|---| | PHPCS | Warning | 3 | 3 warnings (ruleset: Magento2) | | PHPMD | Warning | 5 | 5 rule violations (UnusedFormalParameter:3, UnusedLocalVariable:1, MissingImport:1) | | Cpd | Pass | 0 | | | Composer validate | Info | 1 | valid; 1 advisory note (composer validate --strict) | #### PHPStan Type-checks the module against a real Magento install. Re-runs per Magento + PHP version because resolvable symbols differ between releases. | Magento | PHP 8.2 | PHP 8.3 | PHP 8.4 | PHP 8.5 | |---|---|---|---|---| | 2.4.7 | 17 | 17 | – | – | | 2.4.8 | – | 17 | 17 | – | | 2.4.9 | – | – | 17 | 17 | ### Tests Unit and integration suites run per Magento + PHP cell. Test failures speak to the module's behaviour, not its compatibility with a line, so they're reported here separately. #### Unit Tests | Magento | PHP 8.2 | PHP 8.3 | PHP 8.4 | PHP 8.5 | |---|---|---|---|---| | 2.4.7 | N/A | N/A | – | – | | 2.4.8 | – | N/A | N/A | – | | 2.4.9 | – | – | N/A | N/A | #### Integration Tests | Magento | PHP 8.2 | PHP 8.3 | PHP 8.4 | PHP 8.5 | |---|---|---|---|---| | 2.4.7 | 2 | 2 | – | – | | 2.4.8 | – | 2 | not tested | – | | 2.4.9 | – | – | 2 | 2 | ### Security Dependency-advisory audit (composer audit) plus a source malware scan. A malware detection fails the version outright. | Tool | Status | Findings | Summary | |---|---|---|---| | Composer audit | Pass | 0 | | | Malware scan | Pass | 0 | | ## Licence and pricing Free. A licence is still minted on checkout and bound to your project for Composer access — no payment step. Refundable within 14 days of first purchase via https://packagento.com/account/refunds/. ## Install via Claude Code or any MCP client The Packagento MCP server can run the licence + project + Composer steps above in one tool call: ``` purchase_and_install_packages( composer_names=["mage-os/mageos-async-events"], project_id="proj_xxx" ) ``` This handles cart, checkout, licence minting, project activation, and writes auth.json credentials. Connect a client with `claude mcp add packagento https://mcp.packagento.com`. Full setup at https://packagento.com/docs/mcp-setup. ## Vendor mage-os is a Magento 2 vendor on Packagento. See https://packagento.com/mage-os.md for their full catalogue.