Reacting to Events

Nothing is pushed to your integration, so you either ask again or run your own code where the event happens.

Overview

There is no webhook delivery. That is a deliberate boundary. The installation never holds a queue of your endpoints and never retries against them. It also never leaks work to an address it cannot verify.

Two approaches replace it, and they answer different questions.

Choose by where your code can live. An integration outside the installation polls. A module, an add-on or a theme shipped with the installation listens.

Prerequisites

• For the listener route: somewhere to put PHP inside the installation, which in practice means a module of your own.
• The exact name of the hook you want. Names are catalogued, and one that does not exist fails quietly.

Walkthrough

Pick the Hook

1. Find the moment you care about in the hook catalogue, in the Hooks section of this documentation.
2. Read its parameter list and its mechanism. Some hooks report what happened, others let you change a value, and a third kind can refuse an operation outright.
3. Note the argument count. Declaring more arguments than the hook sends drops your listener.

Register a Listener

1. Put a hooks.php in your module and add the listener there.
2. Keep the body cheap. It runs inside somebody's request, and slow work there is felt by the person waiting.
3. Hand anything slow to a queue, a file or a scheduled task, and let that do the outbound call.

Verify It Runs

1. Trigger the event once for real and confirm your side saw it.
2. If nothing happened, look in the error log before touching the code. One message reports a listener that ran and threw. Another reports a listener whose class or method name could not be resolved.
3. Neither message means the hook name itself is wrong, or the listener returned nothing on purpose.

Example

This listener reacts to a new order and reads it back through the API in the same process. It leaves the outbound call to a queue.

\Hook::add('action:order.created', 10, function (array $order) {
    $id = (int) ($order['id'] ?? 0);
    if (!$id) return;

    // the same resource the HTTP surface exposes, without a key or a round trip
    $full = \WISECP\Api\Kernel::internal('Orders/GetOrder', ['id' => $id]);
    if (isset($full['error'])) return;

    // queue it; do not call your own endpoint from inside someone's checkout
    \Acme\Sync::enqueue('order.created', $full['data']);
});

Pitfalls

Related Articles

• The WISECP API
• API Resources
• How Hooks Work
• Writing a Hook Listener
• Hook Domains