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