Event Platform for Adobe Commerce

Summary

What is the Akeneo Event Platform?

Traditionally, synchronization between a PIM and an e-commerce platform relies on "Pull" technology: your Adobe Commerce system regularly asks Akeneo, "Is there anything new?" (Scheduled Batch/Delta).

The Akeneo Event Platform introduces "Push" technology. Instead of waiting for a scheduled task, Akeneo becomes proactive. As soon as a specific change occurs in the PIM, Akeneo sends an instantaneous notification to Adobe Commerce.

See more information on the Akeneo Event Platform.

Why is it essential for Adobe Commerce?

While most of your product data is synchronized between Akeneo PIM and Adobe Commerce through standard flows (full or delta imports), the Akeneo Events module provides a critical layer of real-time responsiveness.

Why use the Events Platform?

In a standard synchronization architecture, "delta" exports only process created or updated entities. If an entity is deleted in Akeneo PIM, it simply stops appearing in the data flow sent to Adobe Commerce.

Without a specific instruction to delete, Adobe Commerce has no way of knowing the item should be removed, leading to a critical data discrepancy between your PIM source of truth and your online store. The Events Platform solves this by sending an instant notification to Adobe Commerce the moment a deletion occurs in Akeneo.

How the Module Works

The Akeneo Events module acts as a specialized integration layer that maintains the integrity of your Adobe Commerce catalog by processing deletion events in near real-time:

Push Notification: Whenever an entity (product, category, attribute, etc.) is deleted in Akeneo, a webhook is immediately sent to Adobe Commerce.
Queueing: Adobe Commerce receives and secures this notification in a processing queue to ensure reliable execution.
Automated Deletion: The module identifies the corresponding entity in Adobe Commerce and automatically removes it.

By using this mechanism, you ensure that your webstore accurately reflects your Akeneo PIM catalog without manual intervention or waiting for the next scheduled import.

Key Comparison: Batch vs. Event Platform

Scenario	Standard Synchronization (Batch)	Akeneo Events module
Price Update	Processed during the next export (Full or Delta)	Not currently handled by this flow
Product Deletion	Unable to process (the product disappears from the flow)	Immediate deletion in Adobe Commerce
Speed	Depends on job frequency (e.g., every 30 min)	Real-time (within seconds)

Prerequisites

Before installing and enabling the Akeneo Events module, ensure your environment and main connector meet the following requirements:

Akeneo Version Requirements

SaaS Only: This module is compatible exclusively with Akeneo PIM SaaS editions (Serenity) that support the Akeneo Event Platform.

System Requirements

PHP Version: PHP 8.1 or higher is required

Module Dependencies

Akeneo Connector for Adobe Commerce (Enterprise Edition): This module must be installed and fully configured

The Events module does not work standalone. It relies on the entity mapping table generated by the main connector to resolve Akeneo identifiers (like UUIDs) into their corresponding Adobe Commerce identifiers.

Configuration Requirements

Valid Credentials: Your Akeneo PIM credentials (URL, Client ID, Secret, and Token) must be correctly set up in the main connector configuration.
Entity Mapping: Since the module processes deletions based on existing links, at least one initial synchronization of your catalog (products, categories, etc.) should have been performed to populate the mapping tables.

Authorization Requirements

Before deploying artifacts, you must authorize your API Connection to interact with the Event Platform within the Akeneo PIM settings.

In Akeneo, navigate to Connect > Connections.
Select the connection used for your Adobe Commerce integration
Ensure the "Event Platform" capability (checkbox) is enabled

If this box is not checked, the connection will not have the necessary permissions. A specific error message will then be returned by the connector when the subscription is created.

For detailed steps on how to assign these permissions, please refer to the official Akeneo API documentation.

Scope and Limitations

To ensure a smooth integration, it is important to understand exactly which tasks the Akeneo Events module handles and what remains the responsibility of the main connector.

What the Module Does

Real-Time Reception: Listens for and receives deletion notifications sent by the Akeneo Event Platform via webhooks.
Reliable Queueing: Stores incoming notifications in a queue to ensure they are processed even during high traffic or temporary server downtime.
Automated Deletion: Synchronizes your Adobe Commerce catalog by deleting entities that no longer exist in Akeneo.
Subscription Management: Automatically handles the lifecycle of your Akeneo event subscription (creation, updates, suspension, and deletion) based on your Adobe Commerce configuration.

What the Module Does Not Do

No Creations or Updates: This module is dedicated solely to deletions. All product creations and data enrichments (updates) continue to be managed by the standard Akeneo Connector for Adobe Commerce (Enterprise Edition).
Deletion Only: It does not process any other event types (e.g., status changes or associations) beyond the six deletion types listed below.
Allowed data: The module will never delete data not previously imported with the official Akeneo Connector module.

Handled Deletion Events

The module is pre-configured to handle six specific deletion types. When one of these is triggered in Akeneo, the corresponding element is removed from Adobe Commerce:

Akeneo Event	Action in Adobe Commerce	Identification Method
Product deleted	Deletes the Product	via Akeneo Product UUID
Product model deleted	Deletes the Configurable product	via Product Model Code
Category deleted	Deletes the Catalog category	via Category Code
Attribute deleted	Deletes the Product attribute	via Attribute Code
Attribute option deleted	Deletes the Attribute option	via Option Code
Family deleted	Deletes the Attribute set	via Family Code

Installation and configuration

The procedure for installing the module is described here.

To configure the event integration, log in to your Adobe Commerce Admin panel and navigate to:

Stores > Configuration > Akeneo Connector > Events Platform

Parameters	Description
Enable	Toggle this to Yes to activate the real-time event integration.
Subscriber Email	Enter a technical contact email. This is sent to Akeneo to identify who is responsible for the subscription.
Subscribed Events	A multi-select list of the six deletion types. Choose which deletions you want Adobe Commerce to process automatically.
Use Native Message Queue	Yes (Recommended): Uses Adobe Commerce’s message broker (RabbitMQ or MySQL) for automatic background processing. No: Requires manual triggering via CLI commands.
Subscriber ID	A read-only unique identifier generated by Akeneo once the connection is established.
Subscription ID	A read-only ID assigned by the Akeneo Event Platform to this specific integration.
Reset Subscription	Button to delete the subscription from Akeneo and clear local identifiers.

Any changes you save in this configuration panel are automatically synchronized with the Akeneo Event Platform.
For more information on the subscription lifecycle, see the dedicated section.

Technical Workflow: How It Works

The Akeneo Events module follows a secure, three-step process to ensure that every deletion in Akeneo PIM is accurately reflected in Adobe Commerce.

1. Receiving Notifications

Whenever an entity is deleted in Akeneo, an HTTP request is sent to your Adobe Commerce instance.

Security First: Adobe Commerce automatically performs a cryptographic signature validation to verify that the request genuinely originates from Akeneo before any action is taken.
Ingestion: Once validated, the event is immediately placed in a local queue.

2. The Event Queue

Events are stored in the Adobe Commerce database to ensure no data is lost during transit. Each event is assigned a lifecycle status:

Pending: Received and waiting for processing.
Processing: Currently being handled by the system.
Completed: Successfully processed; the entity has been deleted in Adobe Commerce.
Failed: An error occurred (e.g., entity not found or database lock).

Processing Modes

You can choose how these events are triggered in the configuration:

Native Message Queue (Recommended): Uses RabbitMQ or MySQL MQ for automatic background processing. This is the standard for production environments.
Database-only Queue: Events remain stored until manually triggered via the Command Line Interface (CLI).

3. Processing & Deletion

Each event is routed to a specialized handler based on its entity type (Product, Category, etc.).

Mapping Lookup: The handler queries the Akeneo Connector mapping table to find the specific Adobe Commerce ID linked to the deleted Akeneo entity.
Action: If a match is found, the entity is deleted from the Adobe Commerce catalog.
Logging: Every operation, from reception to deletion, is recorded in var/log/akeneo_events.log.

Event Platform Subscription Management

The Akeneo Events module features a "self-managed" connection. It automatically synchronizes your Adobe Commerce store's status with the Akeneo Event Platform, ensuring that notifications are only sent when your system is ready to process them.

The Subscriber vs. The Subscription

To understand the connection, it is helpful to distinguish between these two components:

The Subscriber: This represents your specific Adobe Commerce instance. It is identified by a Subscriber ID and linked to the Technical Email you provide in the configuration.
The Subscription: This represents the "contract" between Akeneo and Adobe Commerce. It defines which specific events (e.g., product deletions) Akeneo is allowed to push to your server.

Automated Lifecycle

The module monitors your configuration changes and updates the Akeneo Event Platform accordingly. No manual intervention in the PIM is required.

When you...	The Module automatically...
Enable the module	Creates the Subscriber and the Subscription in Akeneo
Modify "Subscribed Events"	Updates the existing subscription to add or remove event types
Disable the module	Sets the subscription status to Suspended in Akeneo
Deselect all events	Suspends the subscription (as there is no data to send)
Click "Reset Subscription"	Deletes the subscription and the subscriber from Akeneo, clearing all local IDs

Security & Validation

Every time a subscription is created or updated, a secure handshake occurs:

Handshake: Akeneo and Adobe Commerce exchange secret tokens.
Verification: Adobe Commerce stores the Subscriber ID and Subscription ID (visible as read-only fields in your admin panel).
Signature: All subsequent notifications sent by Akeneo include a cryptographic signature, which Adobe Commerce validates using these stored IDs to ensure the data is authentic.

When to use "Reset Subscription"?

The Reset Subscription button is a powerful tool intended for specific scenarios:

Environment Migration: When cloning a Production database to a Staging environment (to avoid Staging receiving Production events).
Troubleshooting: If the connection IDs between Akeneo and Adobe Commerce become desynchronized.
Clean Uninstall: Before removing the module to ensure no "ghost" subscriptions remain active on the Akeneo side.

Available CLI Commands

The Akeneo Events module provides built-in tools to monitor the health of your synchronization and manage the event queue directly from the Command Line Interface (CLI).

Check Queue Status

Use this command to view the state of your event queue. It displays a table containing IDs, event types, current status, error messages, and timestamps.

php bin/magento akeneo_events:status [--status=<status>]

Option	Short	Description
`--status=<status>`	`-s`	Filter entries by status: pending, processing, completed, or failed.

Examples

# Show all queue entries
php bin/magento akeneo_events:status

# Show only failed entries
php bin/magento akeneo_events:status --status=failed

# Show pending entries
php bin/magento akeneo_events:status --status=pending

Process Queue Entries

While processing is typically automatic, you can manually trigger the execution of specific entries.

Note: At least one of --id or --type is required.

php bin/magento akeneo_events:run [--id=<ID>] [--type=<event_type>] [--force]

Option	Short	Description
`--id=<ID>`		Process a single entry by its unique numeric ID.
`--type=<type>`	`-t`	Process all pending entries of a specific type (e.g., `com.akeneo.pim.v1.product.deleted`).
`--force`	`-f`	Forces re-processing regardless of current status (resets status to pending).