Status updates

The pakketmail api can send status updates for several different events.
This is accomplished in 2 different ways, each with their own purpose.

Shop upates

The first option for updates is targeted at e-commerce plugins. These updates will send specific data to the e-commerce platform if there is an update for a shipment.
The API does this by using the registered url in the very fist token request, sending information on the current status and ofcourse verification that the call was made by this api and not from someplace else.
It doesn't matter how this update has been set up (either through the API using webhooks or in the application with the shop settings), the result and data sent will be the same.

Currently, the following events are supported for shop updates:

When a shipment enters our system
When a shipment is pre-alerted (and accepted) by a carrier
When a shipment has been delivered

If you want to be able to set these updates, we will need information about your e-commerce plugin (or module). In particular, this is a list of valid id's and what those id's mean.
For instance, id 1 could mean: the shipment is in transit.

Nomatter what the update, the data will contain at least the internal id of the platform you used of that shipment, the status id that was set and the tracking id if available.

The mentioned hash in the json data that is sent, is calculated the same as the hash for authenticating your request to the api. This calculation is listed below.

Webhooks

The second method is targeted at a UI or (background) process you might be creating remotely. For instance, it is possible to initiate a label create process and when it is finished it will do a request to a registered webhook when it is finished. This prevents having to code a loop that constantly polls the API.

The webhook will only do a simple GET request to the registered url. A webhook will contain a header with a correct hash using the callback url + the current token as the data to calculate the hash.

Calculating the Hash value

To secure the update request and to make sure it is valid, a hash is calculated and sent with the request.
This calculation is basically the same calculation that is done for doing a request to the API, so you will only need one method in your code. It is best to always check this hash by calculating your own hash and compare this to what is sent.
Because the registered url is (only) known in the API and in your platform there is a high degree of certainty that this update originated from our API.

Hash Calculated security hash (see below)

ShopItemId The same id that was sent with the shipment in ShopItemId

Status Numerical statuscode

TrackingId The tracking id (if available)

TrackingUrl A (direct) URL to the tracking page of the carrier.

1. We concatenate the status id, the tracking code and the registered callback url.

2. We then select the correct secret key and use this to create a HMAC SHA256 hash, and make this base64 encoded.

3. This hash is then inserted as the Hash field in the json data above.

Hash	Calculated security hash (see below)
ShopItemId	The same id that was sent with the shipment in ShopItemId
Status	Numerical statuscode
TrackingId	The tracking id (if available)
TrackingUrl	A (direct) URL to the tracking page of the carrier.

1.	We concatenate the status id, the tracking code and the registered callback url.
2.	We then select the correct secret key and use this to create a HMAC SHA256 hash, and make this base64 encoded.
3.	This hash is then inserted as the Hash field in the json data above.