The following information applies to custom built API connections with Mintsoft. This guide is intended for customers with custom-built third-party API integrations. It provides an additional method for receiving webhook notifications, rather than the standard approach.
Despatched or cancelled webhooks
You can register a Webhook or callback to receive notifications when an order is despatched, split, or cancelled, eliminating the need to poll the API for updates. It is important to note that despatch webhooks differ from tracking notifications provided by the Courier; the despatch notification specifically indicates when the order is marked as despatched on Mintsoft. Additionally, connect actions are included as part of original create order call.
Example
Enter the Order ID in the id field.
Which is returned from put /api/Order
{ "Type": "API", "SourceOrderId": "202-0672909-5683525", "Complete": false, "ExtraCode1”: "https://api.yoursystem.com/callback/OrderDespatched", "ExtraCode2": "https://api.yoursystem.com/callback/OrderCancelled", }SourceOrderId: The Order Number in the system that the order came from.
(3PL Only) This must be unique against each individual 3PL Client.
ExtraCode1: The URL to call when the order has been despatched.
ExtraCode2: The URL to call when the order has been cancelled.
You then receive a POST request back to the specified address when the order is despatched with the same order JSON found on the get /api/Order/{id} call.
Delivered Webhook - Specific courier support only
Note: The Delivery Webhook requires the Tracking Events module to be active on your Mintsoft database.
If you utilise a courier that provides delivery updates to Mintsoft and have the Tracking Events module activated, you can also receive webhooks when the parcel is delivered. To enable this, you need to populate ExtraCode3 while adding a connect action. For example:
{
"ExtraCode3": "https://api.yoursystem.com/callback/OrderDelivered" }The URL is then called when the parcel is delivered with all the events relating to that delivery.
Split Webhook
If an order is split after it has been created, you can register a Webhook to notify you of that split. To do this, simply populate ExtraCode5 when adding a connect action.
Example
{ "ExtraCode5": "https://api.yoursystem.com/callback/OrderSplit" }The system will subsequently call that URL once an order has been divided into multiple parts. You will receive JSON data that includes the original order along with the details of the new split order, providing you with all the information necessary to understand how the order has been divided.
[{ "Order": {}, // Full Details of the Order "SplitOrder": {}, // Full Details of the Split Order "OrderId": 78025, "SplitOrderId": 78026, "ID": 1, "LastUpdated": "2020-10-05T23:36:31.5231781", "LastUpdatedByUser": "groveslu" }]Additional Security Options
When making Webhook calls, you can include an API key in the URL to verify its origin. For instance: https://api.yoursystem.com/callback/OrderDespatched?APIKEY=fe14830f-0980-46c6-a540-04c20a26b01c.
Alternatively, you can provide a specific value in the Authorization header, which will be sourced from ExtraCode4. If the Webhook handler is secured by Basic Auth, you can supply that value in ExtraCode4 to be used in the Authorization header.
username and password become username:password
Base64 encoded becomes dXNlcm5hbWU6cGFzc3dvcmQ=
Example
{ "ExtraCode4": "Basic dXNlcm5hbWU6cGFzc3dvcmQ=" }