Setup Webhooks
Webhooks are a way for our systems to push updates to your defined endpoint with the information you require. Once configured, the webhook will send a POST request via HTTP to your system, where you can then parse the detail and use it to update your system or application.
Updates are triggered by events which happen in our Transport or Warehouse management systems and remove the need for you to poll for data to get the latest details.
In order to setup a webhook you will need to create an endpoint and then setup the webhook details.
Create an Endpoint
To receive a status update, firstly you'll need to configure where it needs to be sent to.
You'll need to know the URL which the updates are to be sent to before you start and it needs to be reachable.
| Field | Type | Description | |
|---|---|---|---|
| Name | Give your Endpoint a name. This name will then display in other areas for you to select. | ||
| URL | Destination for the payload to be sent to. Must include the full address as it would appear in your browser. | ||
| HTTP Headers |
Key Value |
A Key/Value pair for additional headers required to access the nominated URL, e.g. content type or an API key | |
Create a Webhook
Webhooks are a way for our systems to push updates to your defined endpoint with the information you require. Once configured, the webhook will send a POST request via HTTP to your system, where you can then parse the detail and use it to update your system or website.
Updates are triggered by events which happen in our Transport or Warehouse management systems and remove the need for you to poll for data to get the latest details. This makes webhooks a much more efficient means of integration for both your system and ours.
There are a few steps to set up the webhook, so we've provided a grid below to give you the details you need.
| Field | Type | Description | |
|---|---|---|---|
| Name | Give your Webhook a name. This is only for your information, supports free text. | ||
| Endpoint | Select an existing Endpoint. If none exist, you'll need to create one first | ||
| API Key | API keys applied against your account that is enabled for Webhooks, will display in the listbox | ||
| Event Type | Event type describes what kind of events you wish to receive. | ||
| Service Type | Dependant on Event Type. Lists the service and country which relate to your account. If you wish to use multiple services, you'll need to create addtional webhooks. | ||
| Reference Type | Dependant on Service Type selected. This defines the type of reference you wish to be sent. | ||
| Format | Dependant on Reference Type. Selects the format you wish to receive the Reference Type by. | ||
| HTTP Content Type | Request content type. Supported types are "application/json" or "application/xml." | ||
| Events | List of all the available events for your Reference Type. | ||
| Optional Conditions |
Customer Code |
Will limit the events to only those related to the defined Customer Code, only applicable to Logistics | |
| Warehouse Code | Will limit the events to only those related to the defined Warehouse Code, only applicable to Logistics | ||
Basic Template
All webhooks will have the following basic field structure. Each message can have custom metadata and content based on the message type that is subscribed for.
| Parameter | Description | Type | Length |
|---|---|---|---|
| data | object | ||
| id | uniqueidentifier | ||
| metadata | object | ||
| subscriptionId | uniqueidentifier | ||
| subscriptionTransportEventId | uniqueidentifier | ||
| eventTypeCode | string | ||
| referenceTypeCode | string | ||
| eventCode | string | ||
| content | object |
Webhook Retry-On-Fail
Webhooks are considered successfully delivered when 200 HTTP response code is received, any other response code is considered as a failure and the following retry logic is applied.
- 1st attempt, 1-minute wait
- 2nd attempt, 5 minutes wait
- 3nd attempt, 30 minutes wait
- 4th attempt, 1-hour wait
- 5th attempt, considered as failed