Skip to content
Tutorials Center
My learning

Topics

Lesson 38 of 42 ยท Projects

Project: Order Events and Notifications

Build an order notifier in Magento: an observer reacts to a placed order, publishes a queue message, a consumer sends it, and cron retries failures. With runnable stand-ins.

When a customer places an order, other systems often need to know: a warehouse, a chat channel, an ERP, a loyalty program. The naive way is to call that system straight from an observer. That works until the other system is slow or down, and then checkout slows down or fails with it. In this project you build the robust version.

The design has three parts. An observer reacts to the placed order and does almost nothing: it publishes a message to a message queue. A consumer reads the queue and makes the slow call. If the call fails, the notification is stored as failed and a cron job retries it a limited number of times. Magento cannot run on this site, so the real PHP and XML are read-only, and each part has a runnable plain-PHP stand-in that is not Magento code but behaves similarly.

What you will build

flowchart LR
    O["Order placed"] --> E["Event<br/>sales_order_place_after"]
    E --> OB["Observer<br/>publishes message"]
    OB --> Q["Queue<br/>acme.order.notify"]
    Q --> C["Consumer<br/>calls external system"]
    C -->|"ok"| D["Status: sent"]
    C -->|"error"| F["Status: failed"]
    F --> CR["Cron job<br/>retries up to 3 times"]
    CR --> C

Checkout only pays for the cheap publish step. Slow work and retries happen later, outside the customer's request.

The module is Acme_OrderNotifier:

TEXT
app/code/Acme/OrderNotifier/
  etc/module.xml
  etc/events.xml
  etc/communication.xml
  etc/queue_consumer.xml
  etc/queue_topology.xml
  etc/queue_publisher.xml
  etc/crontab.xml
  Observer/PublishOrderNotification.php
  Model/Consumer.php
  Cron/RetryFailedNotifications.php

Step 1: the observer

Declare which event you listen to. sales_order_place_after is dispatched after an order object has been placed. Check in your version's source (search for ->dispatch() which event best fits your case, because order-related events differ slightly in what data and transaction state they carry. The file is global because orders can be placed from the storefront, the admin or the API.

XML
<?xml version="1.0"?>
<config xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
        xsi:noNamespaceSchemaLocation="urn:magento:framework:Event/etc/events.xsd">
    <event name="sales_order_place_after">
        <observer name="acme_order_notifier_publish"
                  instance="Acme\OrderNotifier\Observer\PublishOrderNotification"/>
    </event>
</config>
PHP
<?php
declare(strict_types=1);

namespace Acme\OrderNotifier\Observer;

use Magento\Framework\Event\Observer;
use Magento\Framework\Event\ObserverInterface;
use Magento\Framework\MessageQueue\PublisherInterface;
use Psr\Log\LoggerInterface;

class PublishOrderNotification implements ObserverInterface
{
    public const TOPIC = 'acme.order.notify';

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

    public function execute(Observer $observer): void
    {
        $order = $observer->getEvent()->getData('order');

        try {
            $this->publisher->publish(self::TOPIC, (string) $order->getIncrementId());
        } catch (\Throwable $e) {
            // never break checkout because a notification could not be queued
            $this->logger->error('Could not queue order notification: ' . $e->getMessage());
        }
    }
}

Three design choices deserve a comment:

  • The message holds the increment id only, a small string. The consumer loads the order itself, so it always sees fresh data and the queue never stores sensitive details.
  • The observer catches everything. An exception thrown here would travel back into the order placement code, as explained in the events lesson.
  • It does no network call at all. Publishing writes a row (with the default database-backed queue), which is quick.

Step 2: the queue configuration

Magento's queue framework needs a few XML files. Each has one job. The names below follow the usual conventions for the database-backed queue; confirm attribute names against your version's schemas before shipping.

etc/communication.xml declares the topic and what handles it:

XML
<?xml version="1.0"?>
<config xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
        xsi:noNamespaceSchemaLocation="urn:magento:framework:Communication/etc/communication.xsd">
    <topic name="acme.order.notify" request="string">
        <handler name="acmeOrderNotifyHandler"
                 type="Acme\OrderNotifier\Model\Consumer"
                 method="process"/>
    </topic>
</config>

etc/queue_publisher.xml says where messages for the topic go:

XML
<?xml version="1.0"?>
<config xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
        xsi:noNamespaceSchemaLocation="urn:magento:framework-message-queue:etc/publisher.xsd">
    <publisher topic="acme.order.notify">
        <connection name="db" exchange="magento-db" disabled="false"/>
    </publisher>
</config>

etc/queue_topology.xml binds the topic to a queue:

XML
<?xml version="1.0"?>
<config xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
        xsi:noNamespaceSchemaLocation="urn:magento:framework-message-queue:etc/topology.xsd">
    <exchange name="magento-db" type="topic" connection="db">
        <binding id="acmeOrderNotifyBinding"
                 topic="acme.order.notify"
                 destinationType="queue"
                 destination="acme.order.notify"/>
    </exchange>
</config>

etc/queue_consumer.xml defines the consumer that reads the queue:

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="acmeOrderNotify"
              queue="acme.order.notify"
              connection="db"
              handler="Acme\OrderNotifier\Model\Consumer::process"/>
</config>

Consumers are started by bin/magento queue:consumers:start acmeOrderNotify, or run periodically by Magento's cron-based consumers runner when cron is configured. Run bin/magento queue:consumers:list to confirm yours is registered.

Step 3: a stand-in for the event and the queue

The first stand-in connects the observer and the consumer through an in-memory queue. A property of queues becomes visible: the "customer" part ends as soon as the message is published, and the consumer works later.

PHP An observer that only publishes a message

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with fgets(STDIN)), it gets the next line from this box.

In real Magento the default queue uses MySQL tables, so messages survive restarts. Message brokers such as RabbitMQ are supported when you configure the connection in env.php.

Step 4: the consumer and failure tracking

The consumer is a plain class with one method named in the XML. It must not swallow errors silently, or you lose messages. A simple pattern is to keep your own table of notifications with a status and an attempt counter. The observer or the consumer creates a row; the consumer marks it sent or failed.

PHP
<?php
declare(strict_types=1);

namespace Acme\OrderNotifier\Model;

use Psr\Log\LoggerInterface;

class Consumer
{
    public function __construct(
        private readonly NotificationRepository $notifications,
        private readonly WarehouseClient $warehouse,
        private readonly LoggerInterface $logger
    ) {
    }

    public function process(string $incrementId): void
    {
        $notification = $this->notifications->getOrCreate($incrementId);

        try {
            $this->warehouse->notify($incrementId);
            $notification->markSent();
        } catch (\Throwable $e) {
            $notification->markFailed($e->getMessage());
            $this->logger->warning("Notification for $incrementId failed: " . $e->getMessage());
        }

        $this->notifications->save($notification);
    }
}

NotificationRepository, WarehouseClient and the notification model are your own classes; see Service Contracts and Repositories and Models, Resource Models and Collections for how to build them, and Declarative Schema for the table. Catching the error inside the consumer means the message counts as handled, so the retry is your job, not the queue's. That is the cron job's role.

Step 5: cron retries

etc/crontab.xml registers a job:

XML
<?xml version="1.0"?>
<config xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
        xsi:noNamespaceSchemaLocation="urn:magento:module:Magento_Cron:etc/crontab.xsd">
    <group id="default">
        <job name="acme_order_notifier_retry"
             instance="Acme\OrderNotifier\Cron\RetryFailedNotifications"
             method="execute">
            <schedule>*/10 * * * *</schedule>
        </job>
    </group>
</config>
PHP
<?php
declare(strict_types=1);

namespace Acme\OrderNotifier\Cron;

use Acme\OrderNotifier\Model\Consumer;
use Acme\OrderNotifier\Model\NotificationRepository;

class RetryFailedNotifications
{
    private const MAX_ATTEMPTS = 3;
    private const BATCH_SIZE = 50;

    public function __construct(
        private readonly NotificationRepository $notifications,
        private readonly Consumer $consumer
    ) {
    }

    public function execute(): void
    {
        foreach ($this->notifications->getFailed(self::MAX_ATTEMPTS, self::BATCH_SIZE) as $notification) {
            $this->consumer->process($notification->getIncrementId());
        }
    }
}

The retry job is deliberately bounded: a maximum number of attempts stops an order that can never succeed from looping forever, and a batch size keeps one run short. A real project also needs an alert when a notification reaches the attempt limit, because silent permanent failure is the worst outcome. Cron jobs only run if Magento's cron is installed; see Cron Jobs and Message Queues.

Step 6: a stand-in for failure and retry

The second stand-in uses SQLite as the notification table. A fake warehouse fails for specific orders a set number of times, so the output is deterministic. The "cron" is a function you call by hand.

PHP Consumer, failure table and bounded retries

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with fgets(STDIN)), it gets the next line from this box.

Order 102 recovers on the first cron run. Order 103 keeps failing until it reaches the attempt limit, then stops being retried and is flagged. That final step is what turns a retry loop into something you can operate.

Things to think about

  • Idempotency. A retry can deliver the same notification twice if the first call actually succeeded but the answer was lost. If the receiving system supports an idempotency key, send the increment id as one.
  • Transactions. Events dispatched inside the order transaction may fire before the data is committed. Publishing only an id and loading it later in the consumer avoids reading half-saved data.
  • Observability. Log with the order id in every message, so one search finds the whole story.
  • Alternatives. For a very small shop, calling the external system directly in an observer is simpler, but then you carry the timeout risk at checkout. The queue is the better default when anything is remote.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. Why does the observer only publish a message instead of calling the external system?

    The observer runs inside the customer's request. Publishing is cheap, and the slow, failure-prone call happens later in a consumer.
  2. 2. Why does the message contain only the increment id?

    A small identifier keeps messages light, avoids stale copies of order data and keeps sensitive details out of the queue.
  3. 3. What is the job of the cron retry in this design?

    The consumer records failures; the cron job picks up failed rows below the attempt limit and tries again.
  4. 4. Why limit the number of retry attempts?

    A bound prevents endless retries; after the limit you alert a person instead.

Summary

  • Keep observers tiny: react to sales_order_place_after-style events by publishing a small message and never break checkout.
  • Queue topics are wired through communication.xml, queue_publisher.xml, queue_topology.xml and queue_consumer.xml; consumers run via queue:consumers:start or cron.
  • Track each notification with a status and an attempt counter, so failures are visible.
  • A cron job retries failed rows in small batches with a maximum number of attempts, then raises an alert.
  • Think about idempotency and transaction timing when delivery can repeat.

Next, expose your own data to other systems in Project: A REST Integration Endpoint.