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. This guide will also outline the roles of both clients, who are primarily responsible for implementing webhook notifications, and Mintsoft admins, who verify and ensure correct permission settings.
Additionally, if issues arise with dispatch notifications, refer to troubleshooting guidance for common resolutions.
Prerequisite - Roles and permissions
To use order webhook notifications with custom API connections, you need specific permissions enabled based on your user type:
Mintsoft admins should verify that these permissions are configured correctly to support API integrations.
Admin or warehouse users: Enable the AdminEditOrder permission.
3PL client users: Enable the ClientEditOrder permission.
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.
Clients must ensure that the callback URL is correctly specified in the extracode1 field during order submission and that their systems can handle incoming webhook data.
If dispatch notifications fail to send, ensure webhook configurations are correctly set, and perform a test dispatch to verify functionality.
It is also important to confirm that the client’s system is capable of processing incoming webhook data and the callback URL is active and accessible to prevent failures.
Tip: The Despatch webhook will return the Tracking URL and Tracking Number in the response.
The call used for this action is /api/Order/{id}/ConnectActions.
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=" }Troubleshooting Common Issues
If dispatch updates fail:
Check webhook configurations and ensure they are correctly set.
Verify external courier service names are configured as necessary.
Conduct a test dispatch order to validate notification status.
Consult Mintsoft support documentation or engage support for assistance.
Ensure that the callback URL is active and accessible, and the client’s system is ready to process incoming data.