Subscriptions V2

The Subscriptions V2 API provides webhook notifications for menu changes and order status updates.

Overview

Configure webhook endpoints to receive real-time notifications for order status changes and menu updates. All webhooks use HMAC-SHA256 authentication for security.

Available Events

The API provides seven webhook subscription types:

Menu updated - Triggered when menu entities change
Request to Change Order Status created - General status update requests
Request to Confirm Order created - Merchant confirmation actions
Request to Reject Order created - Merchant rejection actions
Request to Fulfill Order created - Order fulfillment events
Request to make an Order Ready For Pickup created - Pickup readiness notifications
Request to make an Order Out For Delivery created - Delivery dispatch notifications

Webhook Payloads

All events follow a consistent structure with event metadata and payload data.

Menu Updated Event

{
  "event": {
    "name": "online-ordering.Menu.updated",
    "component": "online-ordering",
    "resource": "Menu",
    "action": "updated",
    "version": "v2",
    "subscriptionId": 1,
    "dispatchedAt": "2019-04-05T09:26:00.388Z"
  },
  "payload": {
    "locationId": {{locationId}}
  }
}

Order Confirmation Request

{
  "event": {
    "name": "online-ordering.OrderConfirmRequest.created",
    "component": "online-ordering",
    "resource": "OrderConfirmRequest",
    "action": "created",
    "version": "v2",
    "subscriptionId": 1,
    "dispatchedAt": "2019-04-05T09:26:00.388Z"
  },
  "payload": {
    "status": "CONFIRMED",
    "locationId": {{locationId}},
    "appRef": "{{orderAppRef}}",
    "waitTimeInMinutes": 100
  }
}

Order Rejection Request

{
  "event": {
    "name": "online-ordering.OrderRejectRequest.created",
    "component": "online-ordering",
    "resource": "OrderRejectRequest",
    "action": "created",
    "version": "v2",
    "subscriptionId": 1,
    "dispatchedAt": "2019-04-05T09:26:00.388Z"
  },
  "payload": {
    "status": "REJECTED",
    "locationId": {{locationId}},
    "appRef": "{{orderAppRef}}",
    "message": "Restaurant is offline",
    "rejectionReasons": [
      {
        "code": "STORE_CLOSED",
        "explanation": "Restaurant is offline"
      }
    ]
  }
}

Status Change Requirements

When processing status update webhooks, developers must:

Update the order status field to the requested status
Add entries to statusHistory array with source: APP
For CONFIRMED orders: recalculate pickupInfo.estimatedAt or deliveryInfo.estimatedAt using the provided waitTimeInMinutes

Order Status Change Request

This event is triggered when a merchant submits an request to change the status of the order on the POS side. After this action, Order is locked (action is pending) in the POS, until an Order with the changed status is pushed back to it. Since this event accommodates all of the possible status updates, if the app is subscribed to any of the more granular events, only the latter will be sent out in any relevant situation.

Payload Parameters:

Name	Type	Description
`status`	string (required)	New status which is requesting to change by POS.
`locationId`	integer (required)	The Lighthouse location ID
`appRef`	string (required)	The 3rd-party order reference which was defined in Order creation object
`waitTimeInMinutes`	integer	Required only if status `CONFIRMED`. This represent the remaining wait time in minutes. If this is a delivery order, it is the estimated number of minutes until delivery to the diner.
`message`	string	Required only if status `REJECTED`. Reason for rejecting the order.
`rejectionReasons`	array	Required only if status `REJECTED`. Array of rejection reasons for rejecting the order. At least one reason is provided.

Response: successful response 200 is expected, otherwise the status would not be changed in POS.

Rejection Reason Structure

Name	Type	Description
`code`	string (required)	Rejection reason code. Supported rejection reason codes
`explanation`	string (required)	Rejection reason explanation
`refs`	array	Required only for "resource" specific reason codes, etc, "MISSING_ITEMS"

Supported Rejection Reason Codes

Code	Examples
`POS_NOT_SETUP`	POS/AGENT configuration issue
`POS_NOT_READY`	Sale ring up in progress, Drawer/Till open, End of Day batchout in progress
`POS_OFFLINE`	POS Offline, Internet Outage, Technical issue in-store
`STORE_CLOSED`	Store closed, Orders submitted outside of operational hours, Holiday Hours not honored
`STORE_CAPACITY`	No open capacity slots, Invalid pickup times, Rejected due to busy store
`ORDER_INFO_MISSING`	Missing required Order detail
`ORDER_ADDRESS_INVALID`	Missing required address, Invalid geo-coordinates and/or textual identifier
`ORDER_SPECIAL_INSTRUCTIONS`	Allergen info provided on order, Utensil opt-in / opt-out instruction
`ORDER_TOTALS_MISMATCH`	Mismatch in expected subtotal, Incorrect Tender format
`ITEMS_OUT_OF_STOCK`	Order contains out of stock items, Invalid items references expected
`ITEMS_NOT_AVAILABLE`	Item not available during service hours (Breakfast, Lunch, Late Night, etc.)
`ITEMS_INFO_MISSING`	Item is missing a required choice selection, Invalid quantity rules set in the menu on parent modifier group
`ITEMS_PRICING_MISMATCH`	Mismatch in item pricing
`ITEMS_SPECIAL_INSTRUCTIONS`	Item level instructions on order
`MODIFIERS_OUT_OF_STOCK`	Order contains out of stock items
`MODIFIERS_NOT_AVAILABLE`	Item not available during service hours (Breakfast, Lunch, Late Night, etc.)
`MODIFIERS_PRICING_MISMATCH`	Mismatch in item pricing
`ORDER_CONFIRMATION_WINDOW_EXPIRED`	The POS requested to confirm the order after its confirmation window has been expired on the 3rd-party side
`OTHER`	Generic Error Response, Blank/Null Response

Security

HMAC Authentication

All webhook requests include HMAC-SHA256 authentication headers:

Header	Description
`x-access-key`	Your public client_id
`x-timestamp`	Unix timestamp in seconds
`x-signature`	HMAC-SHA256 digest (hexadecimal)

Response Expectations

All webhook handlers must return HTTP 200 for successful processing
Failure to respond with 200 prevents POS status synchronization
Non-200 responses trigger retry attempts from the POS system

Error Handling

Third-Party Unavailability:

If webhook endpoint returns 4xx or 5xx status codes
Or if endpoint is unreachable
System notifies POS that request wasn't processed
POS must retry the request

Status Conflicts:

Return 4xx status code with descriptive message
Example: Attempting to CONFIRM an expired order
Third-party should immediately transmit updated status back to POS