Partners may optionally register a URL to receive webhook style callbacks to receive asynchronous updates regarding order processing and shipment delivery status.

To register for callbacks, include the callback_url attribute with your Create Order POST request. The API will send POST requests to the supplied URL when the Order or Shipment status changes. The precise format of the POST body is documented with the Create Order POST request.

Your callback URL must be HTTPS and support TLS v1.2+

The Create Order POST request also optionally supports headers, via the attribute callback_headers that will be sent to your webhook endpoint for the purpose of Authentication. You may supply Authorization and/or X-Api-Key headers. For example: callback_headers: {"Authorization": "Bearer AbCdEf123456"}.

Your webhook endpoint must respond with an HTTP 2xx status code within 5 seconds. If there is an error sending the webhook, the API will make 2 additional attempts; the first after a 1 minute delay, and the second after a 2 minute delay. Webhooks will not be retried after 3 attempts have failed.

Note: webhooks will be sent “at least once”, therefore your webhook handler should be idempotent to handle duplicate events without error.

The webhook callback body contains the following fields:

  • id: Unique ID of this Webhook event.
  • order_id: ID of the Order this event relates to.
  • reference_id: Partner supplied reference ID of the Order this event relates to.
  • event_type: The event type will be one of the following: ORDER_CREATED, ORDER_UPDATED, ORDER_CANCELLED, ORDER_ERROR, SHIPMENT_CREATED, SHIPMENT_UPDATED, SHIPMENT_CANCELLED
  • shipment_id: ID of the Shipment this event relates to (optional - populated only if the event is a shipment related event).
  • data: Either an Order or a Shipment object. See API reference for the format of these objects.

Note the content of the data field varies depending on the type of event. For ORDER_* event types, data will be an Order object. For SHIPMENT_* events, data will be a Shipment object. Shipment type events also carry the shipment_id field.

Note: for security purposes, neither the Order or Shipment object sent with the callback event will contain the ship_to field, nor callback_url and callback_headers.

Event Types:

  • ORDER_CREATED: A new Order was created. Typically sent immediately after a “Create Order” POST request.
  • ORDER_UPDATED: An existing Order was updated. Typically sent only once per Order, after the weekly processing and fulfillment cycle. See Sequence Diagram - Place Order
  • ORDER_CANCELLED: An existing Order was cancelled. Typically sent immediately after a “Cancel Order” DELETE request.
  • ORDER_ERROR: An existing Order failed processing. Typically sent only once per Order, after the weekly processing and fulfillment cycle. The Order object will carry 2 fields explaining the reason for the error: error_type and error_details.
  • SHIPMENT_CREATED: A Shipment was created. Sent upon label creation during the weekly processing and fulfillment cycle. The Shipment data object will contain delivery information such as the Carrier, Tracking Code, and Tracking URL.
  • SHIPMENT_UPDATED: A Shipment was updated. This event is typically sent multiple times up-to and including delivery for each delivery status change we receive from the carrier. The fields delivery_status, delivery_status_detail, and est_delivery_date are supplied by the carriers and can be used to inform your users regarding the status of their deliveries. Possible delivery_status values are: “UNKNOWN”, “PRE_TRANSIT”, “IN_TRANSIT”, “OUT_FOR_DELIVERY”, “DELIVERED”, “AVAILABLE_FOR_PICKUP”, “RETURN_TO_SENDER”, “FAILURE”, “CANCELLED” or “ERROR”.
  • SHIPMENT_CANCELLED: An existing Shipment was cancelled. This event will only be sent in response to a “late cancel”, in the rare event that an Order was cancelled after the weekly order processing cycle.