Outgoing Events
When using the events approach, there are two mechanisms for receiving notifications about customer order status changes (e.g., an order being picked up in store).
Customer Order Events (WebHook)
When using the events approach, the service also emits dedicated customer order events when an order is updated -- for instance, when a customer order is picked up in store.
Key characteristics:
- Same schema as the PUT request -- the event payload matches the schema used for incoming events, simplifying the mapping for external systems.
- Delivered via WebHook -- events are emitted to a WebHook topic using the Hii Retail ExternalEvents framework, allowing for straightforward integration with external systems.
- Focused notifications -- unlike PosLogs, these events are specific to customer order updates, eliminating the need for filtering.
Using the dedicated customer order events can reduce the processing load compared to subscribing to the full PosLog stream, and provides a more streamlined integration for systems that only need customer order status updates.
PosLog Subscription
The PosLog subscription is available regardless of whether you use the proxy or events approach. PosLogs are emitted for various POS activities including login, regular sales, refunds, and customer order pickups. To detect customer order events, the external system must filter the PosLog stream to identify the relevant entries.
PosLogs are delivered via WebHook through the Hii Retail ExternalEvents framework, the same delivery mechanism used for the dedicated customer order events described below.
This option remains available when using the events approach, so existing integrations that rely on PosLogs continue to work.
Choosing Between PosLog and Customer Order Events
The external system should subscribe to one event type per order -- either PosLog or Customer Order events, not both. Using both for the same order can lead to processing redundant or conflicting information. Choose the event type that best fits your integration needs:
| PosLog | Customer Order Events | |
|---|---|---|
| Scope | All POS operations (requires filtering) | Customer order updates only |
| Schema | PosLog format | Same schema as the PUT request |
| New orders created by POS | Not visible until paid or fulfilled | Emitted for all updates, including new orders |
If using PosLog events, new customer orders created directly at the POS will not be visible to the external OMS until the order is paid or picked up by the customer. This is because PosLogs are only emitted for fulfilled or paid orders. To receive events for new orders as well, use the Customer Order events.
Customer Order events are designed for external OMS systems that need easy access to customer order state updates. Other systems such as accounting or financial systems should use PosLog data, which contains the financial information needed for those purposes.