Webhook
What is webhook?
Webhooks are a useful tool for applications that want to execute code after a specific event happens, for example, after a purchase order is created, or a return is confirmed, or an order is shipped.
You can use webhook subscriptions to receive notifications about particular events.
Instead of telling your app to make an API call every X number of minutes to check if a specific event has occurred on a shop, you can subscribe to webhooks. When the event you have registered for occurs, the Moduslink API portal will trigger a notification to your application.
This will reduce the number of API calls your system has to make, allowing you to build more efficient apps, and update your app instantly after a webhook is received.
Webhook events you can subscribe to:
Webhook events
Client will register a webhook endpoint as per our specifications where Moduslink will post trigger events to notify when there is a change in order processing. The webhook event will be a light weight message conveying the actual event, order reference and information to construct the unique URL of Moduslink status check API to fetch the complete order status. Moduslink clients will have the flexibility to subscribe for the events they are interested to be notified using this webhook mechanism.
The table below provides comprehensive list of identified events and description.
Configure a webhook
As part of the onboarding process, ModusLink will configure the applicable Webhook events. The configured events can be changed at any time depending on the requirements or needs.
You will need to provide the endpoint(s) to receive the Webhook message to Moduslink so we can have the endpoint(s) setup as part of the configuration.
Receive a webhook
Once you register a webhook URL with ModusLink, we will issue a HTTPS POST request to the configured URL every time that event occurs. The request's POST message will contain JSON data relevant to the event that triggered the request.
The message will have the following information:
Sample Order Webhook message:
{
"eventType":"Orders.Created",
"eventObjectId":"42000631",
"eventObjectName":"orders",
"eventObjectReference":"Your_ref_60",
"eventDateTime":"2019-03-27T14:58:03",
"links":[
{
"href":"/fulfillmentapi/v1.2/orders/42000631",
"rel":"orders"
}
]
}Sample Return Webook message:
{
"eventType":"Rmas.Created",
"eventObjectId":"42000631",
"eventObjectName":"rmas",
"eventObjectReference":"Your_ref_60",
"eventDateTime":"2019-03-27T14:58:03",
"links":[
{
"href":"/fulfillmentapi/v1.2/rmas/42000631",
"rel":"rmas"
}
]
}Sample PO Webhook message:
{
"eventType":"PurchasedOrders.Confirmed",
"eventObjectId":"42000631",
"eventObjectName":"purchaseorders",
"eventObjectReference":"Your_ref_60",
"eventDateTime":"2019-03-27T14:58:03",
"links":[
{
"href":"/fulfillmentapi/v1/orders/42000631",
"rel":"purchaseorders"
}
]
}Below table describes the relevant fields in the webhook message
Please note standard each webhook will trigger once, if successfully received. It is however possible a webhook will trigger multiple times, or skips a intermediate status, as due to the asynchronous nature of our webhook queue processing a status can be 'overtaken' by a subsequent status if they did happen in close proximity.
Respond to webhook
Your webhook acknowledges that it received data by sending a 200 OK response. Any response outside of the 200 range will let ModusLink know that you did not receive your webhook. Moduslink does not follow redirects for webhook notifications and will consider a redirection as an error response.
For every webhook connection error, an automatic retry is attempted 5 times with 5 minute intervals. After that it will be dropped from the queue
If you're receiving a ModusLink webhook, the most important thing to do is respond quickly.
Verify a webhook created by Moduslink
Webhooks created by ModusLink API can be verified by calculating a digital signature.
Each webhook request includes a base64-encoded X-Moduslink-HMAC-SHA256 header, which is generated using the app's shared secret along with the data sent in the request.
To verify that the request came from ModusLink, compute the HMAC digest value and compare it to the value in the X-Moduslink-HMAC-SHA256 header. If they match, you can be sure that the Webhook was sent from ModusLink and the data has not been compromised.
Excluding the padding characters (=) from the HMAC Base64 output is supported for backward compatibility. However, we recommend that you keep the padding characters, as they are required by the Base64 standard.
The examples below demonstrate how to verify a WebHook request in different languages.
