Webhooks

When first getting started using webhooks you need to make sure you either have an active integration or valid API credentials.

To get started using integrations click here.
To get started using the API click here.

Creating a webhook

To add your first webhook you must go to the webhook overview. In the overview click the button 'Webhook toevoegen' to enter the form where you can configure your preferences.

If you want to create a webhook based on an integration you should select the desired integration from the dropdown. When you want to create a webhook that is not based on an integration you should select the API client you wish to create a webhook for. Finally you should select the event type you wish to use and the URL the webhook will be posted to.

Webhook overview

In the webhook overview you can see all your webhooks displayed in a list including the edit and remove action. This is also where you can go to the webhook create form.

Event triggers

Types

There are 4 webhooks types which can be used.

Webhook-label-create
Webhook-label-update
Webhook-shipment-create
Webhook-shipment-update

The triggers will be executed once the event happens. A POST request with JSON-data will be sent to the provided URL.

Data layout

Below is an example of the JSON-data that will be sent for a webhook-label-update event. Within the payloud you can find the actual data. The object using key "active" is where the current label status will be displayed along with the distributorcode, description provided by the distributor, date and the receiver. The object using key "details" will display the same information for all previously received statusses.

{
  "id": "a639a370-2423-11eb-8fbe-0242ac12000f",
  "event": "webhook-label-update",
  "date": "2020-11-11T14:36:28.252463Z",
  "payload": {
    "reference": "511",
    "waybill": "3SFBFX2176804",
    "active": {
      "status": "delivered",
      "code": "postnl",
      "description": "delivered",
      "date": {
        "date": "2020-11-11 15:36:23.000000",
        "timezone_type": 3,
        "timezone": "Europe/Amsterdam"
      },
      "receiver": null
    },
    "details": [
      {
        "status": "in_transit",
        "code": "postnl",
        "description": "in_transit",
        "date": {
          "date": "2020-11-11 15:25:24.000000",
          "timezone_type": 3,
          "timezone": "Europe/Amsterdam"
        },
        "receiver": null
      },
      {
        "status": “scanned”,
        "code": "postnl",
        "description": "scanned",
        "date": {
          "date": "2020-11-11 15:28:53.000000",
          "timezone_type": 3,
          "timezone": "Europe/Amsterdam"
        },
        "receiver": null
      },
      {
        "status": "created",
        "code": "postnl",
        "description": "created",
        "date": {
          "date": "2020-11-11 15:36:23.000000",
          "timezone_type": 3,
          "timezone": "Europe/Amsterdam"
        },
        "receiver": null
      }
    ]
  },
  "hmac": "84cc264b423915c1a97e098b4aca049e0637b590f96edc0556bd8ccf341ab2e4"
}

Security

For security options a HMAC key will be provided in the JSON-data. It will be based on a combination of an algorithm, the data send and a key. To check if the key matches the one provided by the JSON-data from Boekuwzending you should create an identical HMAC key and compare the two.

Creating the HMAC key

To create the HMAC key you should create one using the sha256 algorithm, as data use the provided payload and as key use a combination of the clientId and clientSecret

ApiLabels