☰Notifications Guide
Authentication
As a Merchant user that calls into our APIs, you must authenticate by including an OAuth 2.0 access token in the request header. You can obtain this token by following the instructions in this Authentication guide.
Submitting Orders
You can submit individual orders using our recommended order format by sending a POST API request directly to a Create a new Order endpoint and even submit multiple orders in a single POST API request to our Create multiple orders endpoint.
To be notified if your order was successfully created or failed to be created in our system, as well as keep track of all the order updates that happen after the order submission, you’ll need to subscribe to Webhooks that contain event information related to a specific order. You can configure your Webhooks by following the instructions in this Webhook Configuration guide.
Order Creation
First, you’ll need to set up a webhook for order creation events. Order Creation webhook is triggered whenever an order is successfully created or whenever an order has failed to be created in our system.
Next to the basic information that describes the event, the webhook payload will also contain:
OrderId- This is your new Order ID.ExternalOrderId- Your internal Order ID.SafeId- The Safe ID for the order.
You’ll be able to distinguish a successfully created from a failed order notification by responseCode and responseDescription values:
Order has been successfully created - at which point you should receive:
{“Notification”: {“IsSuccessful”: true,“Reprint”: null,“OrderId”: “670e58fe7741035996cf7d20”,“ExternalOrderId”: “WBTEST_123”,“SafeId”: "WebhooksTest123",“Description”:“Order created”,“SubscriberId”: “261c6102-0b72-4506-9a84-98a80a03e7f0",“ChildSubscriberId”: null,“RequestId”: “20251125T165208Z-17d49f5bff84gkz6hC1AMShtc800000008dg0000000073hv”,“EventType”: “OrderCreation”}}
Order failed to be created - at which point you should receive:
{“Notification”: {"IsSuccessful": false,"ResponseCode": 400,"Reprint": null,"ExternalOrderId": "WBTEST_123","SafeId": "WebhooksTest123","Description": "Order could not be created","SubscriberId": "261c6102-0b72-4506-9a84-98a80a03e7f0","ChildSubscriberId": null,"RequestId": "116e90b04bf38fbf53b83933abdae219","EventType": "OrderCreation"}}
Please note that the failed order Webhook is triggered only in case you're submitting orders via POST API request to the inbound/orders endpoint and transforming your order payload. In case you're submitting orders via POST API request directly to a Create a new Order endpoint, you'll receive a response directly from our Orders API notifying you that the order creation failed.
Order Update
You’ll also need to set up a Webhook for Order Update events. Order Update Webhook is triggered whenever an order information is updated/changed. Some of those updates include order status changes, order item status changes, shipping or billing address updates, image file updates, etc.
Next to the basic information that describes the event, the webhook payload will also contain:
OldStatus- This is the order status before the update.NewStatus- This is the order status after the update.
{
“Notification”: {
“NewStatus”: “ReadyForFulfillment”,
“OldStatus”: “Open”,
“Reprint”: null,
“OrderId”: “670e58fe7741035996cf7d20”,
“ExternalOrderId”: “WBTEST_123",
“SafeId”: "WebhooksTest123",
“Description”: “Order updated: status updated from Open to ReadyForFulfillment”,
“SubscriberId”: “261c6102-0b72-4506-9a84-98a80a03e7f0”,
“ChildSubscriberId”: null,
“RequestId”: “20251125T165208Z-17d49f5bff84gkz6hC1AMShtc800000008dg0000000073hv”,
“EventType”: “OrderUpdate”
}
}
Once you receive an Order Update event Webhook you can use the OrderID or Order SafeID in that payload to then make a GET call to the Order API and retrieve the full order data if needed.
Shipment Created
Order Items within the order are grouped into Shipments that can get assigned to multiple vendors, depending on the product type and your Routing Strategy. Shipment Created Webhook is triggered when a shipment is created.
Next to the basic information that describes the event, the Webhook payload will also contain:
shipmentId- This is a unique shipment identifier.{"Notification": {"ShipmentId": "3ed09cf5-80c4-4450-8c64-245f2e2061bc","ResponseCode": 200,"OrderId": "670e58fe7741035996cf7d20","ExternalOrderId": "WBTEST_123","SafeId": "WebhooksTest123","Description": "OK","SubscriberId": "261c6102-0b72-4506-9a84-98a80a03e7f0","ChildSubscriberId": null,"RequestId": "20251125T165208Z-17d49f5bff84gkz6hC1AMShtc800000008dg0000000073hv","EventType": "ShipmentCreated"}}
Once you receive a Shipment Created event Webhook you can use the ShipmentID in that payload to then make a GET call to the Shipment API and retrieve the full shipment data.
Shipment Update
Shipment Update is triggered whenever a shipment is updated or moves into a new status. For example, once a shipment is produced and shipped it will be updated with tracking information. At that point you’ll receive a Webhook that contains the tracking information for that specific shipment.
{
"Notification": {
"ShipmentId": "3ed09cf5-80c4-4450-8c64-245f2e2061bc",
"Package": {
"PackageId": "6e4d1eb2-493f-4664-a784-57d26412738a",
"ShortId": "P09680270",
"CarrierName": "USPS",
"CarrierMethodName": "USPS Ground Advantage",
"ShippedDate": "2025-04-10T15:20:00",
"FulfilledDate": "2025-04-10T13:05:00",
"CarrierTrackingNumber": "9400136208551280752547",
"CarrierLink": "https://tools.usps.com/go/TrackConfirmAction.action?tLabels=9400136208551280752547",
"CarrierAccount": false,
"OrderItemIDs": [
"670e58fe7741035996cf7d21"
],
"PackingSlipId": null
},
"OrderId": "670e58fe7741035996cf7d20",
"ExternalOrderId": "WBTEST_123",
"SafeId": "WebhooksTest123",
"Description":"Package was successfully updated with tracking information",
"SubscriberId": "261c6102-0b72-4506-9a84-98a80a03e7f0",
"ChildSubscriberId": null,
"RequestId": "0HN78H2O038E4:0000001C",
"EventType": "ShipmentUpdate"
}
}
Once you receive a Shipment Updated event Webhook you can use the information in that payload to pass it back into your system and update the order with the corresponding tracking information.