Magento Webhooks: Sending Events Reliably to External Systems

1. Why polling falls short for external systems

The most obvious way to notify external systems about changes in Magento is a cron job that periodically queries new or modified records. This pattern works, but it creates two structural problems: latency and unnecessary load. A five-minute polling interval means that, in the worst case, an ERP system finds out about a new order five minutes late. At the same time, every poll cycle executes a database query regardless of whether anything actually changed. With several connected systems and short intervals, this adds up to noticeable extra load on the database, especially during peak times when resources are already tight. Magento webhooks solve this problem in a fundamentally different way: instead of the external system asking, Magento actively reports the change the moment it happens.

Event-driven integration through reliable webhooks delivers changes in real time, without an external system having to guess how often it should ask. That not only reduces latency to a matter of seconds, it also fully decouples the polling frequency from the actual rate of change. A shop with few orders per hour produces correspondingly little traffic, a shop with high frequency produces more, but in both cases the traffic is proportional to what is actually happening rather than to an arbitrarily chosen interval. This exact ratio of effort to benefit is what makes event dispatching more attractive than polling in practice as soon as more than one external system needs to be connected.

Adobe Commerce has, for a number of versions now, shipped a native, declarative webhooks feature as part of its out-of-process extensibility, which lets you define webhooks through XML configuration without writing custom PHP code. That is an attractive option for pure Commerce installations. This article, however, deliberately focuses on the observer-plus-queue solution because it works identically in Magento Open Source and Adobe Commerce, gives full control over payload versioning, signing and retry behavior, and thereby forms the portable foundation for reliable webhooks in mixed or Open Source environments.

2. The observer as trigger: which events qualify

Magento fires events at countless points in its codebase, but only some of them are suitable triggers for Magento webhooks. Good candidates are events that mark a completed, business-relevant state: sales_order_place_after for new orders, catalog_product_save_after for product changes and customer_save_after for customer master data. These events fire after the actual save operation, meaning the entity is already persisted at that point and can be reliably reloaded from the database by its ID. Events that fire mid-transaction or before the actual persistence step are unsuitable, because at the moment of webhook triggering it is not yet certain whether the change will actually be committed.

Registration follows the usual pattern via events.xml, either globally or scoped to the relevant area (frontend, adminhtml, webapi_rest), depending on the context the event is fired from. Each observer implements \Magento\Framework\Event\ObserverInterface and is uniquely identified by its name value, so that later modules can disable the observer via disable if needed, without touching the class itself.

<!-- app/code/Mironsoft/Webhook/etc/events.xml -->
<?xml version="1.0"?>
<config xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
        xsi:noNamespaceSchemaLocation="urn:magento:framework:Event/etc/events.xsd">
    <!-- Fires after a sales order transaction is fully committed -->
    <event name="sales_order_place_after">
        <observer name="mironsoft_webhook_order_placed"
                  instance="Mironsoft\Webhook\Observer\PublishOrderPlacedEvent" />
    </event>
    <!-- Fires after a catalog product entity has been persisted -->
    <event name="catalog_product_save_after">
        <observer name="mironsoft_webhook_product_saved"
                  instance="Mironsoft\Webhook\Observer\PublishProductSavedEvent" />
    </event>
    <!-- Fires after a customer entity has been persisted -->
    <event name="customer_save_after">
        <observer name="mironsoft_webhook_customer_saved"
                  instance="Mironsoft\Webhook\Observer\PublishCustomerSavedEvent" />
    </event>
</config>

The most important architectural principle for Magento webhooks: the observer itself must never perform the HTTP call synchronously. An observer runs within the same request as the triggering action, meaning a checkout request would block until the external endpoint responds. If that endpoint is slow, unreachable or times out, the entire customer checkout process hangs on it. On top of that, a hard coupling is created: a failure in the external system would directly cause the Magento request to fail, even though the actual Magento operation (creating the order, saving the product) had already succeeded. The only robust solution is to limit the observer to a single, extremely fast task: placing a lightweight message on a message queue and returning immediately.

3. Decoupling through the message queue

Decoupling the trigger from the delivery is the core of any robust implementation of Magento webhooks. The observer publishes only a lightweight message, in the simplest case consisting of the entity ID and the event type, to a topic on the message queue. A separate consumer, running outside the original request and typically as its own system process, consumes this message asynchronously and takes care of the actual webhook delivery, including signing, the HTTP call and error handling. This pattern uses Magento's built-in message queue infrastructure, which is built on top of RabbitMQ as the default broker and is configured through communication.xml, queue_topology.xml and queue_consumer.xml.

The practical benefit of this separation shows up immediately in the failure case: if the consumer fails because the external endpoint is unreachable, that only affects the asynchronous delivery process. The original checkout or save request has long since completed and remains unaffected, invisibly to the customer. The publisher call itself, meaning placing the message on the queue, typically takes a few milliseconds and should never be allowed to endanger the main process even when it fails, which is why wrapping the publish call in a try-catch block is mandatory.

<?php
declare(strict_types=1);

namespace Mironsoft\Webhook\Observer;

use Magento\Framework\Event\Observer as EventObserver;
use Magento\Framework\Event\ObserverInterface;
use Magento\Framework\MessageQueue\PublisherInterface;
use Magento\Sales\Model\Order;
use Psr\Log\LoggerInterface;

/**
 * Publishes a lightweight message to the webhook dispatch topic after a
 * sales order has been placed. Does not perform any HTTP call itself,
 * it only enqueues the event for asynchronous delivery by the consumer.
 */
class PublishOrderPlacedEvent implements ObserverInterface
{
    private const TOPIC_NAME = 'mironsoft.webhook.order.placed';

    public function __construct(
        private readonly PublisherInterface $publisher,
        private readonly LoggerInterface $logger
    ) {
    }

    /**
     * Reacts to sales_order_place_after and enqueues a webhook message.
     * The message stays intentionally small: entity id and event type
     * are enough, the consumer reloads the full order when it runs.
     *
     * @param EventObserver $observer
     * @return void
     */
    public function execute(EventObserver $observer): void
    {
        /** @var Order $order */
        $order = $observer->getEvent()->getOrder();

        try {
            $this->publisher->publish(self::TOPIC_NAME, json_encode([
                'entity_id' => (int) $order->getEntityId(),
                'event_type' => 'order.placed',
                'occurred_at' => (new \DateTimeImmutable())->format(DATE_ATOM),
            ]));
        } catch (\Throwable $exception) {
            // A queue publishing failure must never break checkout
            $this->logger->error('Webhook publish failed', ['exception' => $exception->getMessage()]);
        }
    }
}

4. Payload design: stable, versioned DTOs

A common beginner mistake with Magento webhooks is serializing the complete entity as the payload and sending it to the receiver unchanged. That may seem convenient at first, but it inevitably leads to breaking changes: as soon as an internal field is renamed, an attribute is removed or the structure of a collection changes, the external consumer breaks, without anyone having intended it. The robust alternative is a stable, explicitly versioned data transfer object that only contains the fields meant to be a public contract, and that exists independently of internal refactorings of the Order or Product entity.

PHP 8.4 with constructor property promotion and readonly properties is an excellent fit for such DTOs: the payload is immutable after construction, all fields are typed, and a mapper handles the one-time translation from the internal entity into the stable, versioned structure. A schemaVersion property in the payload makes it possible to ship a second version of the contract in parallel in the future, without breaking existing consumers, should a later change actually become incompatible.

<?php
declare(strict_types=1);

namespace Mironsoft\Webhook\Model\Dto;

/**
 * Stable, versioned payload contract for the "order.placed" webhook event.
 * Only fields that are safe to expose to external systems are included,
 * intentionally decoupled from the internal Order entity structure.
 */
final class OrderPlacedPayloadV1
{
    public function __construct(
        public readonly string $eventId,
        public readonly string $eventType,
        public readonly int $schemaVersion,
        public readonly string $orderIncrementId,
        public readonly string $orderStatus,
        public readonly float $grandTotal,
        public readonly string $currencyCode,
        public readonly string $occurredAt
    ) {
    }
}

/**
 * Maps a Magento order entity to the stable, versioned webhook payload.
 * Keeping the mapping in a single place ensures that internal field
 * renames on the Order entity never leak into the public webhook contract.
 */
final class OrderPlacedPayloadMapper
{
    /**
     * Builds the versioned payload DTO for a given order.
     *
     * @param \Magento\Sales\Api\Data\OrderInterface $order
     * @param string $eventId Unique identifier generated once per event
     * @return OrderPlacedPayloadV1
     */
    public function map(\Magento\Sales\Api\Data\OrderInterface $order, string $eventId): OrderPlacedPayloadV1
    {
        return new OrderPlacedPayloadV1(
            eventId: $eventId,
            eventType: 'order.placed',
            schemaVersion: 1,
            orderIncrementId: (string) $order->getIncrementId(),
            orderStatus: (string) $order->getStatus(),
            grandTotal: (float) $order->getGrandTotal(),
            currencyCode: (string) $order->getOrderCurrencyCode(),
            occurredAt: (new \DateTimeImmutable())->format(DATE_ATOM)
        );
    }
}

5. Security: HMAC signature and replay protection

An endpoint that accepts Magento events via HTTP POST is fundamentally a publicly reachable attack surface if it is not secured. The standard approach for reliable webhooks is an HMAC-SHA256 signature of the payload, sent along as a header, typically X-Webhook-Signature. The receiver computes the same signature using the shared secret over the received raw body and compares it against the header value. If both match, it is confirmed that the payload actually came from Magento and was not altered in transit.

The secret itself must never live in plain text in configuration. Magento provides the Magento\Config\Model\Config\Backend\Encrypted backend model for system.xml fields, which encrypts the value before it is stored in the core_config_data table using the crypt key stored in env.php. When reading, EncryptorInterface::decrypt() decrypts the value again for the signature computation. In addition to the signature, replay protection belongs in the standard toolkit: a timestamp is sent along and included in the signature computation, and the receiver rejects requests whose timestamp lies outside a tolerance window of a few minutes. This prevents an intercepted but validly signed request from being replayed arbitrarily far into the future.

<?php
declare(strict_types=1);

namespace Mironsoft\Webhook\Model\Queue;

use Magento\Framework\App\Config\ScopeConfigInterface;
use Magento\Framework\Encryption\EncryptorInterface;
use Magento\Framework\HTTP\Client\Curl;
use Mironsoft\Webhook\Model\ResourceModel\DeliveryLog;
use Psr\Log\LoggerInterface;

/**
 * Consumes queued webhook messages and delivers them to the configured
 * external endpoint via a signed HTTP POST request. Signature and
 * timestamp headers allow the receiver to verify authenticity and to
 * reject stale, replayed requests.
 */
class WebhookDeliveryConsumer
{
    private const SIGNATURE_HEADER = 'X-Webhook-Signature';
    private const TIMESTAMP_HEADER = 'X-Webhook-Timestamp';

    public function __construct(
        private readonly Curl $httpClient,
        private readonly ScopeConfigInterface $scopeConfig,
        private readonly EncryptorInterface $encryptor,
        private readonly DeliveryLog $deliveryLog,
        private readonly LoggerInterface $logger
    ) {
    }

    /**
     * Entry point invoked by the Magento consumer runner for each message.
     *
     * @param string $serializedPayload JSON-encoded webhook payload
     * @return void
     * @throws \RuntimeException if the endpoint responds with a server error
     */
    public function process(string $serializedPayload): void
    {
        $endpointUrl = (string) $this->scopeConfig->getValue('mironsoft_webhook/general/endpoint_url');
        $secret = $this->encryptor->decrypt(
            (string) $this->scopeConfig->getValue('mironsoft_webhook/general/signing_secret')
        );

        // Timestamp is part of the signed string, enabling replay protection
        $timestamp = (string) time();
        $signature = hash_hmac('sha256', $timestamp . '.' . $serializedPayload, $secret);

        $this->httpClient->setHeaders([
            'Content-Type' => 'application/json',
            self::TIMESTAMP_HEADER => $timestamp,
            self::SIGNATURE_HEADER => $signature,
        ]);
        $this->httpClient->setTimeout(5);

        $startedAt = microtime(true);

        try {
            $this->httpClient->post($endpointUrl, $serializedPayload);
            $statusCode = $this->httpClient->getStatus();
            $latencyMs = (int) round((microtime(true) - $startedAt) * 1000);

            $this->deliveryLog->record($endpointUrl, $statusCode, $latencyMs, null);

            if ($statusCode >= 500 || $statusCode === 0) {
                throw new \RuntimeException(sprintf('Webhook endpoint returned status %d', $statusCode));
            }
        } catch (\Throwable $exception) {
            $this->logger->warning('Webhook delivery failed, will be retried', ['exception' => $exception->getMessage()]);
            // Rethrow so the queue framework requeues the message per queue_consumer.xml
            throw $exception;
        }
    }
}

6. Guaranteeing delivery: retry, backoff and dead letter queue

External systems are not always available. A temporary 503 error, a timeout or a maintenance window on the receiving end must not permanently discard a message as long as there is a reasonable chance a later delivery attempt will succeed. The standard pattern for reliable webhooks is a retry with exponential backoff: the first retry follows after a few seconds, each subsequent attempt waits twice as long as the previous one, up to an upper limit of attempts. On RabbitMQ, the broker Magento uses by default, delayed redelivery can be elegantly modeled using a dead letter exchange with a message TTL: a failed message moves into a retry queue with a limited lifetime, expires there, and is then automatically redelivered to the original destination queue.

If a message remains undeliverable even after the maximum number of attempts, it belongs in a genuine dead letter queue, from which it is not automatically redelivered but is instead held for manual inspection. Alongside that, it is worth maintaining a dedicated database table, for example webhook_delivery_log, that records every delivery attempt with a timestamp, target URL, HTTP status code, latency and a unique event ID. This table is the foundation for later monitoring and makes it possible to precisely reconstruct afterward when a webhook was attempted, how many times, and with what result.

<!-- app/code/Mironsoft/Webhook/etc/communication.xml -->
<?xml version="1.0"?>
<config xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
        xsi:noNamespaceSchemaLocation="urn:magento:framework-message-queue:etc/communication.xsd">
    <topic name="mironsoft.webhook.order.placed" request="string" />
</config>

<!-- app/code/Mironsoft/Webhook/etc/queue_topology.xml -->
<?xml version="1.0"?>
<config xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
        xsi:noNamespaceSchemaLocation="urn:magento:framework-message-queue:etc/queue_topology.xsd">
    <exchange name="mironsoft.webhook" type="topic" connection="amqp">
        <binding id="orderPlacedBinding" topic="mironsoft.webhook.order.placed"
                 destinationType="queue" destination="mironsoft.webhook.delivery">
            <arguments>
                <!-- Failed messages are routed to the retry exchange with a TTL -->
                <argument name="x-dead-letter-exchange" xsi:type="string">mironsoft.webhook.retry</argument>
            </arguments>
        </binding>
    </exchange>
</config>

<!-- app/code/Mironsoft/Webhook/etc/queue_consumer.xml -->
<?xml version="1.0"?>
<config xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
        xsi:noNamespaceSchemaLocation="urn:magento:framework-message-queue:etc/consumer.xsd">
    <consumer name="mironsoftWebhookDeliveryConsumer"
              queue="mironsoft.webhook.delivery"
              connection="amqp"
              maxMessages="500"
              class="Mironsoft\Webhook\Model\Queue\WebhookDeliveryConsumer"
              method="process" />
</config>

7. Idempotency on the receiver side

Message queue systems typically guarantee at-least-once delivery, not exactly-once. Concretely, that means a consumer can, in rare cases, process the same message more than once, for example when an acknowledgement to the broker gets lost even though the delivery itself succeeded, or when a retry is triggered even though the original attempt actually reached the receiver. For Magento webhooks this means: every message carries a unique event ID that stays stable across all delivery attempts, and it is the receiver's responsibility to detect duplicates using that ID.

The practical recommendation for the receiver implementation: the incoming event ID is stored in a dedicated table or set with a sufficiently long retention period before business processing begins. If an event ID arrives a second time, the receiver immediately returns a success status without re-executing the processing. This pattern, often called an idempotency key or deduplication key, is considerably more robust than trying to eliminate duplicates entirely on the sender side, which can never be guaranteed one hundred percent in distributed systems anyway.

In addition, the receiver should ideally make the processing itself idempotent, for example through an upsert instead of a plain insert when importing an order into an ERP system. Combined with deduplication based on the event ID, this creates a delivery chain that produces exactly one business effect even when the same message is delivered multiple times, regardless of how often the underlying message was technically transmitted.

8. Admin configuration: system.xml and ACL

For Magento webhooks to be adjustable without a code deployment, the configuration belongs in the Magento admin area. Through system.xml you can store endpoint URLs per event type, a global on/off switch and the signing secret as an encrypted field. The fields support the usual scope settings (showInDefault, showInWebsite, showInStore), so webhooks can be enabled differently per store view or routed to different endpoints, for example when a test store sends against a staging environment of the external system while the live store sends against production.

Every new configuration menu requires its own ACL entry, so access in the admin area can be restricted by role. The ACL resource tree hangs below Magento_Config::config, so administrators who generally are not allowed to view system configuration also cannot see the webhook settings. The following example shows both files working together.

<!-- app/code/Mironsoft/Webhook/etc/adminhtml/system.xml -->
<?xml version="1.0"?>
<config xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
        xsi:noNamespaceSchemaLocation="urn:magento:module:Magento_Config:etc/system_file.xsd">
    <system>
        <tab id="mironsoft" translate="label" sortOrder="200">
            <label>Mironsoft</label>
        </tab>
        <section id="mironsoft_webhook" translate="label" type="text" sortOrder="300"
                 showInDefault="1" showInWebsite="1" showInStore="1">
            <label>Webhooks</label>
            <tab>mironsoft</tab>
            <resource>Mironsoft_Webhook::config</resource>
            <group id="general" translate="label" type="text" sortOrder="10"
                   showInDefault="1" showInWebsite="1" showInStore="1">
                <label>General</label>
                <field id="enabled" translate="label" type="select" sortOrder="10"
                       showInDefault="1" showInWebsite="1" showInStore="1">
                    <label>Webhooks Enabled</label>
                    <source_model>Magento\Config\Model\Config\Source\Yesno</source_model>
                </field>
                <field id="endpoint_url" translate="label" type="text" sortOrder="20"
                       showInDefault="1" showInWebsite="1" showInStore="1">
                    <label>Endpoint URL for order.placed</label>
                </field>
                <field id="signing_secret" translate="label" type="obscure" sortOrder="30"
                       showInDefault="1" showInWebsite="0" showInStore="0">
                    <label>Signing Secret</label>
                    <backend_model>Magento\Config\Model\Config\Backend\Encrypted</backend_model>
                </field>
            </group>
        </section>
    </system>
</config>

<!-- app/code/Mironsoft/Webhook/etc/acl.xml -->
<?xml version="1.0"?>
<config xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
        xsi:noNamespaceSchemaLocation="urn:magento:framework:Acl/etc/acl.xsd">
    <acl>
        <resources>
            <resource id="Magento_Backend::admin">
                <resource id="Magento_Backend::stores">
                    <resource id="Magento_Backend::stores_settings">
                        <resource id="Magento_Config::config">
                            <resource id="Mironsoft_Webhook::config" title="Webhook Configuration" />
                        </resource>
                    </resource>
                </resource>
            </resource>
        </resources>
    </acl>
</config>

9. Monitoring, debugging and comparing delivery approaches

Without monitoring, any implementation of Magento webhooks remains a black box. Every delivery attempt should be logged with status code, latency and event ID, either in the previously mentioned webhook_delivery_log table or additionally through Magento's own logging via Psr\Log\LoggerInterface. On top of this table, a simple admin grid can be built that lists failed deliveries from the last 24 hours, filterable by event type and HTTP status code, so a support agent without database access can tell whether a particular endpoint is currently having problems.

For debugging individual cases, it helps to store the delivery attempt including the request body and response in the log, though with caution around personal data in the payload. A comparison of the three common delivery approaches shows why queue-based webhook delivery is the more robust choice in practice as soon as more than one external system needs to be reliably supplied.

The somewhat higher initial implementation effort of the queue-based approach pays off as early as the second connected integration: new consumers simply read from the same queue without anything needing to change on the observer or the triggering code. This exact extensibility is what makes reliable webhooks over a message queue the more sustainable architectural choice compared to isolated synchronous solutions.

10. Summary

Robust Magento webhooks are not the result of a single HTTP call, but of several building blocks working together: a lean observer that never sends blocking requests itself, a message queue for decoupling, a versioned DTO as a stable contract, an HMAC signature with replay protection, a retry strategy with a dead letter queue, and a complete delivery log for monitoring and debugging. Each of these building blocks addresses a concrete failure scenario that inevitably becomes a problem in a naive synchronous implementation as soon as the external endpoint is ever slow, faulty or temporarily unreachable.

The decisive advantage of this architecture is its portability: it works identically in Magento Open Source and Adobe Commerce, without depending on proprietary Commerce-only features, even though Adobe Commerce offers a convenient alternative for pure Commerce installations with its declarative webhooks feature. Anyone who builds event dispatching from the start using an observer, a queue and signed delivery can connect further event types and further receivers at any time without changing the underlying architecture.

11. FAQ: Magento Webhooks