Guides Callbacks / Webhooks

In order endpoint, it is possible to supply a callback_url. Every time a status changes for a specific order, the Probo API will push a message to the URL you supply. In this manor your system gets update the correct status.

Best Practice

We urge you to implement this logic over pooling for the correct order status.

Before you can receive the webhooks you need to supply an URL in every order post. You can do this by adding the property callback_urls in the order post. The property should contain an array with a minimum of one URL.

Setting it up


{
  ...
  "callback_urls": [
    "https://my.callback.url"
  ]
  ...
}

After you have set up the callback url, we will post a message every time after an order update is available.

A possible message will be a after a new order is posted. The orders will be added to a queue.

Example order queued


{
  "status": "queued",
  "message": "Order queued",
  "order": {
    "id": "my_weborder_1234",
    "reference": "Banner 510 for customer X"
  }
}

When your order is accepted, you will received a message that the order is accepted.

Example order accepted


{
  "status": "accepted",
  "message": "Order accepted",
  "order": {
    "id": "my_weborder_1234",
    "supplier_order_number": 202012345,
    "reference": "Banner 510 for customer X"
  }
}

When the order is not accepted, due to already existing order with same id the callback to the provided callback url includes the following payload

Example not accepted


{
  "status": "not_accepted",
  "message": "Order not accepted, reason: | Order with customer order id 'my_weborder_1234' for customer '9999' already exist",
  "order": {
    "id": "my_weborder_1234",
    "reference": "Banner 610 for customer X"
  }
}

When the order has been received (after "queued" and before "accepted"), the files still have to be downloaded and preflighted. When an error occurs in downloading or preflighting a callback will be made to the specified endpoint. A common cause of a preflighting error is a missing or not-allowed spot-color in the file.

When the order is not accepted, due to a file error the callback to the provided callback url includes the following payload (example):

Example file rejected


{
  "status": "not_accepted",
  "message": "File rejected, could not be processed",
  "file": {
    "id": 1
  },
  "order": {
    "id": "my_weborder_1234",
    "reference": "Banner 610 for customer X"
  }
}

When track and trace information is available for a specific order, additional information is returned in the payload. Per the shipped package, a tracking URL and barcode is returned.

Example callback with shipment information

{
 "status": "shipment_in_transit",
"message": "Shipment In Transit",
"order": {
"id": "my_weborder_1234",
"reference": "Banner 610 for customer X",
"supplier_order_number": 1240176000,
"status_page_url": "https://print-status.com/1240176000/26436785d82dc14f2b2e36asds274149ca52354bb134473cfc72ec68e291d1c"
 },
"shipped_packages": [
 {
"id": "1",
"tracking_url": "https://my.dhlparcel.nl/home/tracktrace/JVGL88888888888881/9999+AA?lang=nl_NL",
"barcode": "JVGL88888888888881"
 },
 {
"id": "2",
"tracking_url": "https://my.dhlparcel.nl/home/tracktrace/JVGL0573517001648303/9999+AA?lang=nl_NL",
"barcode": "JVGL88888888888882"
 }
 ]
}

Good to know:

Most order statusses, will push trigger a message on your url
We always try to add your order id (not ours) in the callback, so you can match the order in your system
You need to supply the callback URL on every order post. Orders without this callback will not receive an update.