Ordering Notifications via Webhooks

The system supports callbacks to Partners/Subscribers when changes to the order status have been made to the order or order line level. This allows the subscriber to receive a message when the status has changed.

To enable order & order line notification callbacks, complete the following onboarding steps:

Provide a public HTTPS endpoint
Share the callback URL where BHN should send order and orderLine status notifications.
Set up a callback listener
Implement a listener that can receive and process callback messages from BHN.
Choose an authentication method
Confirm whether your endpoint requires authentication. If authentication is required, select one of the supported methods:
- API Key (recommended)
- Basic authentication (username/password)
- OAuth 2.0
Choose the events to subscribe to
Confirm the order-level and orderLine-level status events you want to receive.
Provide custom headers, if required
If your endpoint requires custom headers for validation, routing, or other processing, provide the header names and expected values.

After this information is provided, the onboarding team configures the notification setup. When configuration is complete, run a validation test and share the results with the onboarding team.

The following tables include the Order and Order Line events that Partner can subscribe to:

Order Status	Descriptions
NEW	The order request was created to go through the order lifecycle
PROCESSING	The order is undergoing internal processes of validations.
REJECTED	The order request was rejected due to issues such as Invalid requests, product unavailability.
CANCELLED	The order was cancelled before fulfillment was complete.
COMPLETED	The fulfillment provider successfully generated the card, and the eGift URL was received.

OrderLine Status	Descriptions
NEW	The orderLine request was created to go through the order lifecycle
PROCESSING	The orderLine is undergoing internal processes of validations.
REJECTED	The orderLine request was rejected due to issues such as Invalid requests, product unavailability.
CANCELLED	The orderLine was cancelled before fulfillment was complete.
COMPLETED	The fulfillment provider successfully generated the card, and the eGift URL was received.

The following tables includes the Order and Order Line Payload fields:

Order Event Payload Fields	Description
entityType	ORDER
orderId	Order GUID created by Ordering API
orderNumber	Numeric value created by Ordering API when an order is created
orderStatus	Status of the order
externalId	Calling application order reference ID
externalPONumber	Purchase order number used by accounting for purposes such as reconciliation.
id	Event id, can help filter for duplicates
locale	Locale for the specific order

Order Line Item Payload Fields (If the data is null for a field, it will not appear in the notification payload)	Description
orderId	Order GUID created by Ordering API
orderLineId	Orderline GUID created by Ordering API
orderLineStatus	Status of the orderLine
quantity	Number of items ordered for the line item
faceValue	Represents the amount including the value and currency
shippingTrackingInfo	Array containing shipping information
actualShippingMethod	Actual Shipping Address, if adjusted from inbound order request
shipmentTrackingNumber	Tracking number of items shipped, returned if applicable (Applicable to Physical orders only)
shippingURL	URL to track Shipment (Applicable to Physical orders only)
messageType	Provision type, Physical or Digital
schedule	Deferred delivery date
externalLineId	Calling application order line reference Id
shippedDate	The actual shipped date received from downstream
eventTimestamp	The time when the event was sent out
cardReferenceInfo	Array of cardReferenceIds in a line item
cardReferenceId	Card Identifier for a particular line item
id	Event id, can help filter for duplicates

Order Level Payload Sample

{
    "event": {
        "entityType": "ORDER",
        "orderId": "01JRZ37TPZEFANBET3490GKT2K",
        "orderNumber": "9733-25549854-9018",
        "externalPONumber": "TSTSUDOo789oCT10000011111",
        "locale": "en_US",
        "orderStatus": "COMPLETED",
        "externalId": "DB3E04AF452E4BA897EE7663C5002",
         "id": "01JF0EEW4CNV2MMCZV35K97D4D"
    }
}

OrderLine Payload Sample

{
  "event": {
    "entityType": "ORDERLINE",
    "messageType": "DIGITAL",
    "orderId": "01JRZ2KVAMT6CP080QTB73HQ1Z",
    "orderLineId": "01JRZ2KVAMMGJ4AGJS6FCF5Z9Q",
    "orderLineStatus": "COMPLETED",
    "quantity": 1,
    "faceValue": {
      "value": 20.0,
      "currency": "USD"
    },
    "eventTimestamp": "2025-04-16T10:35:10.974Z",
    "shippedDate": "2025-04-16T10:34:18.910Z",
    "id": "01JF0EEW4CNV2MMCZV35K97D4D",
    "cardReferenceInfo": [
      {
        "cardReferenceId": "23YFEYDDJDNSKDOSDOWOS546464"
      }
    ]
  }
}

{
    "event": {
        "entityType": "ORDERLINE",
        "messageType": "PHYSICAL",
        "orderId": "01JMR16QVX82P1QF604AK2VM8H",
        "orderLineId": "01JMR16QVY012PDD8TMCVYDQFR",
        "orderLineStatus": "COMPLETED",
        "shippingTrackingInfo": [
            {
                "shippingTrackingNumber": "948883441903",
                "shippingURL": "http://wwwapps.ups.com/WebTracking/track?track=yes&trackNums=948883441903",
                "actualShippingMethod": "UPS Next Day"
            }
        ],
        "quantity": 6,
        "faceValue": {
            "value": 10.0,
            "currency": "USD"
        },
        "externalLineId": "TEST-EXT-LINEID-001",
        "eventTimestamp": "2025-02-23T00:02:52.417Z",
        "shippedDate": "2025-02-23T00:02:51.940Z",
        "id": "01JMR1TABYE3MD07PZQF70FDR8",
        "cardReferenceInfo": [
            {
                "cardReferenceId": "23YFEYDDJDNSKDOSDOWOS546464"
            },
            {
                "cardReferenceId": "23YFEFBHFKSDW374683SKDOSDOWOS"
            }
        ]
    }
}