Skip to content
Tutorials Center
My learning

Topics

Lesson 24 of 27 ยท Real-world projects

Project: Order Webhook Exporter

Build an OpenCart extension that sends signed order webhooks: an event queues each status change, a worker delivers with retries and backoff, and an admin screen shows the log.

Sooner or later a store has to tell another system about its orders: a warehouse, an accounting tool, a chat channel, a CRM. The simplest implementation is a curl call inside the code that confirms an order. It works in testing and then fails in production in the worst possible way: the other system is slow, so checkout is slow, or it is down, so the order is lost or the customer sees an error for an order that was in fact placed.

This project builds the robust version, Acme Order Webhooks. An event writes a tiny row into a queue table and returns immediately. A separate worker delivers the rows with a signed request, retries failures with backoff, and gives up (but remembers) after a limit. An admin screen shows what was sent and lets you retry dead messages. OpenCart cannot run on this site, so the extension code is read-only, while the queue, the signer, the retry schedule and a receiver are runnable plain-PHP stand-ins. The same ideas, from the receiving side, are in Webhooks and Signatures and Idempotency, and the reasoning about slow remote calls is in Performance in Extensions.

The design

flowchart LR
    O["Order status changes"] --> E["Event after addHistory"]
    E --> Q["Queue table<br/>status: pending"]
    W["Worker<br/>(cron, every minute)"] --> Q
    W --> D["Signed HTTP POST"]
    D -->|"2xx"| OK["delivered"]
    D -->|"error or timeout"| R{"attempts left?"}
    R -->|"yes"| P["pending again<br/>after a delay"]
    R -->|"no"| X["dead"]
    X -.->|"admin clicks retry"| Q

Checkout only pays for one cheap insert. Everything slow happens later, in the worker.

Five design decisions:

  1. At-least-once delivery. The worker may deliver the same message twice (for example if it crashes after the receiver answered). So each message carries a stable event id, and the receiver must ignore ids it has seen.
  2. Sign every request with a shared secret and a timestamp so the receiver can prove who sent it.
  3. Retry with growing delays (backoff), so a receiver that is down for an hour is not hammered every second.
  4. A limit, then a dead state. Endless retries hide problems. After the last attempt the row becomes dead and shows up in the admin.
  5. No secrets or card data in payloads or logs. Send what the receiver needs (order id, status, total, currency), not payment details.

Files

TEXT
extension/acme/
  install.json
  admin/controller/module/webhook.php     settings, log list, retry action
  admin/model/module/webhook.php          log queries
  admin/view/template/module/webhook.twig
  catalog/controller/event/webhook.php    event handler: enqueue only
  catalog/controller/cron/webhook.php     worker entry point (secured)
  catalog/model/module/webhook.php        queue operations
  system/library/acme/webhook/signer.php  signing and backoff (pure PHP)

Step 1: the queue table (read-only)

SQL
CREATE TABLE IF NOT EXISTS `oc_acme_webhook_queue` (
  `queue_id` INT(11) NOT NULL AUTO_INCREMENT,
  `event_id` VARCHAR(40) NOT NULL,
  `order_id` INT(11) NOT NULL,
  `body` TEXT NOT NULL,
  `status` VARCHAR(12) NOT NULL DEFAULT 'pending',
  `attempts` TINYINT(3) NOT NULL DEFAULT 0,
  `next_attempt` DATETIME NOT NULL,
  `last_error` VARCHAR(255) NOT NULL DEFAULT '',
  `date_added` DATETIME NOT NULL,
  PRIMARY KEY (`queue_id`),
  UNIQUE KEY `event_id` (`event_id`),
  KEY `due` (`status`, `next_attempt`),
  KEY `order_id` (`order_id`)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_general_ci;

The index on (status, next_attempt) serves the worker's "what is due now" query, as discussed in the performance lesson. The unique event_id guarantees that the same event cannot be queued twice, even if your event handler runs twice. Create the table in install() and drop it only if the merchant agrees in uninstall(); see Install, Uninstall and Permissions.

Step 2: the event handler (read-only)

In OpenCart, an order becomes a real order when its first status history is added, and every later status change goes through the same model method. So one event covers both "order placed" and "status changed":

PHP
<?php
public function install(): void {
    $this->load->model('setting/event');

    // Action separator and addEvent() keys can differ slightly between 4.0.x releases: copy the style of a bundled extension.
    $this->model_setting_event->addEvent([
        'code'        => 'acme_webhook_history',
        'description' => 'Queue a webhook when an order status changes',
        'trigger'     => 'catalog/model/checkout/order/addHistory/after',
        'action'      => 'extension/acme/event/webhook.queue',
        'status'      => 1,
        'sort_order'  => 10
    ]);
}
PHP
<?php
namespace Opencart\Catalog\Controller\Extension\Acme\Event;

class Webhook extends \Opencart\System\Engine\Controller {
    // Arguments of addHistory(): $args[0] order id, $args[1] new order status id
    public function queue(string &$route, array &$args, mixed &$output): void {
        if (!$this->config->get('module_acme_webhook_status')) {
            return;
        }

        $orderId  = (int)($args[0] ?? 0);
        $statusId = (int)($args[1] ?? 0);

        if (!$orderId || !$statusId) {
            return;
        }

        try {
            $this->load->model('extension/acme/module/webhook');
            $this->model_extension_acme_module_webhook->enqueue($orderId, $statusId);
        } catch (\Throwable $e) {
            $this->log->write('Acme webhook enqueue failed: ' . $e->getMessage());
        }
    }
}

Look at what the handler does not do: no remote call, no heavy query, and no exception escaping. A failure to queue is logged, and the customer's checkout continues. The model builds the payload from the order and inserts the row with an event id such as evt_<order>_<status>_<timestamp>.

PHP
<?php
public function enqueue(int $orderId, int $statusId): void {
    $this->load->model('checkout/order');
    $order = $this->model_checkout_order->getOrder($orderId);

    if (!$order) {
        return;
    }

    $body = json_encode([
        'event_id' => 'evt_' . $orderId . '_' . $statusId . '_' . time(),
        'type'     => 'order.status_changed',
        'order_id' => $orderId,
        'status'   => $order['order_status'],
        'total'    => (int)round($order['total'] * $order['currency_value'] * 100),
        'currency' => $order['currency_code'],
        'email'    => $order['email']
    ]);

    $this->db->query("INSERT IGNORE INTO `" . DB_PREFIX . "acme_webhook_queue`
        SET `event_id` = '" . $this->db->escape(json_decode($body, true)['event_id']) . "',
            `order_id` = '" . $orderId . "',
            `body` = '" . $this->db->escape($body) . "',
            `status` = 'pending',
            `next_attempt` = NOW(),
            `date_added` = NOW()");
}

The payload includes the customer's email because many integrations need it; if yours does not, leave it out. Personal data in a queue table is data you must also protect and eventually delete.

Step 3: signing and backoff (runnable)

The signature follows the pattern from the payment project: HMAC-SHA256 over timestamp.body, sent in a header. The retry delay is a small table indexed by the number of failed attempts. In production you add a little random jitter to each delay so many failed messages do not all retry at the same second; the stand-in leaves it out so its output is the same on every run.

PHP Signing a webhook and the backoff schedule

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.

Step 4: the worker (runnable stand-in)

The worker runs every minute. Each run does the following, which the stand-in below reproduces with SQLite, a pretend clock and a fake receiver:

  1. Select a small batch of rows that are pending and due.
  2. Claim each row by changing its status to sending with a conditional UPDATE ... WHERE status = 'pending'. If the update affected zero rows, another worker run got there first, so skip it. This stops two overlapping cron runs from sending the same message twice.
  3. Send the signed request with short timeouts.
  4. On a 2xx answer, mark the row delivered. Otherwise increase attempts, store the error, and either schedule the next try or mark the row dead when the attempt limit is reached.

The fake receiver verifies the signature, fails on purpose for some orders, and ignores event ids it has already stored.

PHP A queue, worker and receiver over simulated time

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.

Read the log from top to bottom. Order 9 is delivered at once (and queued only once, thanks to the unique key). Order 7 fails twice with 503 and succeeds on its third attempt, five minutes after the second. Order 8 fails every time, waits longer after each failure, and after the fifth attempt becomes dead with its last error saved. Nothing here ever blocked a customer.

Step 5: the worker entry point (read-only)

You need something that calls the worker once a minute. Recent OpenCart 4 releases include a scheduled-task mechanism, but how it is triggered differs between releases and hosting setups, so check the documentation for your version. A dependable alternative is the operating system's cron calling a protected route or a small PHP script. If you use an HTTP route, protect it with a long random key stored in the extension settings and compared with hash_equals(); an unauthenticated worker URL lets anyone trigger deliveries.

PHP
<?php
namespace Opencart\Catalog\Controller\Extension\Acme\Cron;

class Webhook extends \Opencart\System\Engine\Controller {
    public function run(): void {
        $key = (string)($this->request->get['key'] ?? '');

        if (!hash_equals((string)$this->config->get('module_acme_webhook_cron_key'), $key)) {
            http_response_code(403);
            return;
        }

        $this->load->model('extension/acme/module/webhook');

        // Return rows stuck in 'sending' for more than 10 minutes (a crashed run) to 'pending'
        $this->model_extension_acme_module_webhook->releaseStuck(600);

        foreach ($this->model_extension_acme_module_webhook->claimDue(20) as $row) {
            $this->deliver($row);
        }
    }

    private function deliver(array $row): void {
        $now    = time();
        $header = 't=' . $now . ',v1=' . hash_hmac('sha256', $now . '.' . $row['body'], $this->config->get('module_acme_webhook_secret'));

        $curl = curl_init($this->config->get('module_acme_webhook_url'));
        curl_setopt_array($curl, [
            CURLOPT_POST           => true,
            CURLOPT_POSTFIELDS     => $row['body'],
            CURLOPT_HTTPHEADER     => ['Content-Type: application/json', 'X-Acme-Signature: ' . $header, 'X-Acme-Event-Id: ' . $row['event_id']],
            CURLOPT_RETURNTRANSFER => true,
            CURLOPT_CONNECTTIMEOUT => 3,
            CURLOPT_TIMEOUT        => 8,
        ]);
        curl_exec($curl);
        $code = (int)curl_getinfo($curl, CURLINFO_RESPONSE_CODE);
        $error = curl_error($curl);
        curl_close($curl);

        $this->model_extension_acme_module_webhook->recordResult((int)$row['queue_id'], $code, $error);
    }
}

claimDue() performs the conditional update from the stand-in, recordResult() implements the delivered, pending and dead branches, and releaseStuck() handles a crashed run. Note the timeouts: the worker is not a customer's request, but a hanging receiver would still block the whole batch.

Step 6: the admin log screen (read-only)

The admin needs to answer "did order 4812 reach the warehouse?". A list page shows the queue newest first, with the status, attempts and last error, a filter by status, and a Retry button for dead rows. The retry resets the status to pending and next_attempt to now; it is a state-changing action, so it checks the modify permission and the user_token.

PHP
<?php
public function retry(): void {
    $this->load->language('extension/acme/module/webhook');
    $json = [];

    if (!$this->user->hasPermission('modify', 'extension/acme/module/webhook')) {
        $json['error'] = $this->language->get('error_permission');
    }

    $queueId = (int)($this->request->get['queue_id'] ?? 0);

    if (!$json) {
        $this->load->model('extension/acme/module/webhook');
        $this->model_extension_acme_module_webhook->requeue($queueId);   // UPDATE ... SET status='pending', attempts=0, next_attempt=NOW() WHERE queue_id=? AND status='dead'
        $json['success'] = $this->language->get('text_retry_queued');
    }

    $this->response->addHeader('Content-Type: application/json');
    $this->response->setOutput(json_encode($json));
}

The list query uses LIMIT and OFFSET built from integers, and the status filter is compared against a fixed list of allowed values rather than placed into SQL as typed. In the Twig template, every value from the table (especially last_error, which may contain text from the receiver) is escaped by Twig's default behaviour; do not apply |raw to it. Treat it like any other untrusted text, as taught in Security for Extension Developers.

Purge old rows. A nightly job that deletes delivered rows older than 30 days keeps the table small and limits how long personal data stays in it.

What the receiver must do

Your documentation for whoever receives the webhooks should say: verify the signature and timestamp; answer 2xx fast and do slow work afterwards; ignore an event_id it has already processed, because delivery is at-least-once; and expect messages to arrive out of order, so compare the order's status or a version instead of assuming sequence.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. Why does the event handler only insert a row instead of calling the remote URL?

    Remote systems can be slow or down. Queueing keeps the customer's request fast and safe, and the worker deals with delivery later.
  2. 2. Two cron runs overlap. How does the conditional UPDATE ... WHERE status = 'pending' help?

    The update is atomic. Whichever run changes the status from pending to sending owns the row, and the other run sees zero affected rows and skips it.
  3. 3. A receiver was down for three hours. What does the retry schedule with growing delays achieve?

    Backoff spaces out retries so a recovering service is not overloaded, and the attempt limit prevents endless retrying.
  4. 4. Why does every message carry a stable event_id?

    A message can be delivered more than once, for example after a timeout. A stable id lets the receiver process each event only once.

Summary

  • Never call a remote system from the request that confirms an order; queue a row in an event and deliver in a worker.
  • Use addHistory/after as the trigger, keep the handler tiny, and catch every exception.
  • Sign each request with HMAC over timestamp and body, send a stable event id, and design for at-least-once delivery.
  • Claim rows with a conditional update, retry with growing delays, stop at a limit, and keep dead rows visible.
  • Secure the worker entry point, set timeouts, release stuck rows and purge old data.
  • Give the admin a log screen with a permission-checked, token-protected retry action.

Next: Practice Exercises with Solutions