Events

Envelope & transport

Events are published to AWS EventBridge (or a local Event Router) over two paths:

  1. App/request path — events raised during request handling (order created, updated, etc.).
  2. Workflow task path — events raised as each workflow task executes.

Each published event carries the event bus name, a source identifier, a detail-type (the event type, e.g. PAYMENT_BLOCK, ORDER_SHIPPED), and a detail payload containing the relevant orderId, instanceId, and business data. Internal platform events wrap the detail as a data object plus event metadata.

  • Bus: set by EVENT_BUS_NAME. Source: set by SERVICE_NAME. Region: set by AWS_REGION.
  • Gating:
  • OMS_USE_INMEMORY=true → real EventBridge skipped; events are captured in memory and drive the in-memory state machines instead.
  • LOCAL_EVENT_ROUTER_URL set → publishes to that HTTP router instead of AWS.
  • STAGE=test → event publishing disabled.
  • bypassWorkflowValidation on the payload → the workflow trigger rule drops the trigger event.

Published event types (detail-type)

Task-driven events are defined per workflow task configuration. Each fires when its workflow task executes.

detail-type Trigger (task / action)
ACCOUNTS_BLOCK AccountsBlock (account validation)
PROMOTION_BLOCK PromotionBlock (promotion validation)
PAYMENT_BLOCK PaymentBlock (payment review)
INVENTORY_BLOCK InventoryBlock (inventory review)
INVENTORY_RESERVATION_CONFIRM InventoryConfirm
PROMOTION_ASSIGN PromotionAssign
CANCEL_PAYMENT CancelPayment (cancel compensation)
PAYMENT_REFUND RefundPayment
CANCEL_INVENTORY CancelInventory
PAYMENT_CHARGE PaymentChargeUpdate (on ship)
INVENTORY_SHIPMENT_UPDATE InventoryUpdate (on ship)
PROMOTION_CANCEL CancelRevertPromotion
PAYMENT_UNDO UndoPayment
INVENTORY_UNDO UndoInventory / ReplaceUndoInventory
ACCOUNTS_UNDO UndoAccounts
ACCOUNTS_CANCEL_RELEASE CancelAccounts
ACCOUNTS_BUDGET_RELEASE AccountBudgetRelease
ORDER_DELETED DeleteOrder / OrderDeletedNotification
REPLACE_UNDO_PAYMENT_REQUESTED ReplaceUndoPayment
CANCEL_APPROVAL CancelApproval human task (notify)
SHIPMENT_ADMIN ShipmentAdmin human task
ORDER_CONFIRMED OrderCreatedNotification
ORDER_SHIPPED OrderShippedNotification
ORDER_CANCELLED OrderCancelledNotification
ORDER_RETURN_SUBMIT ReturnSubmittedNotification
ORDER_RETURN_ACCEPTED ReturnAcceptedNotification
ORDER_RETURN_REFUNDED RefundProcessedNotification
ORDER_REPLACE OrderReplaceNotification
ORDER_EXCHANGE OrderExchangeNotification
ORDER_PARTIAL_RETURN OrderPartialReturnNotification

The PATCH /v1/orders/:orderId/externalevents/resend endpoint republishes a previously-emitted event type; INVALID_EVENT_TYPE if the type is unknown.

Consumed events

A single dispatcher routes incoming events by their detail-type:

Incoming detail-type / source Handling
app.* (source Marketplace Service) Marketplace app lifecycle handled by the marketplace integration
returnCollected Warehouse/3rd-party signal → starts the return-collection workflow for a Replace/Exchange child order
External service result events (e.g. PAYMENT_COMPLETED, Reservation.RESERVED, and other *_COMPLETED/callback types) Resumes the waiting workflow task via its task token

Mode notes

  • The in-memory event publisher and state machine are test/in-memory implementations, not production publishers.
  • EVENT_PUBLISH_FAILED (EQ-OMS-5000003) is logged but non-blocking for order mutations.

Revision History
2026-08-05 | JP – Created the page and added the content.