Sending behavior
Webhooks Grouping
Ship24 can either send updates one by one, which means the Trackings array in the webhook message will always contain 1 and only 1 update, or group multiple updates into one webhook message, which means the Trackings array may contain multiple updates.
This behavior is controlled by the "Maximum number of updates per webhook message" setting that you can find in your dashboard.
By default, on recent accounts, Ship24 will send updates one by one, which means the Trackings array will contain only 1 update, which is usually easier and faster to process.
If you prefer to receive more updates per webhook to reduce the number of webhooks you receive, please contact us to update this setting. Please note that receiving more updates per webhook implies grouping them. Therefore, a delay of around 15 minutes is applied to wait for a grouping opportunity. The actual number of updates in each webhook message may vary, in the sense that updates will be pushed to you after these 15 minutes, even if the number of pending updates doesn't reach the maximum number of updates per webhook message value. This allows to not delay updates too much and guarantees a good balance between grouping and the timeliness of information.
Example with a maximum number of updates per webhook message at "1" (Default)
{
"trackings": [ // The trackings object always contains one tracking update for a single shipment. Its length is always 1.
{
"metadata": {
"generatedAt": "2021-03-04T18:12:39.052Z",
"messageId": "356a7f93-3ce5-4b49-b560-156537283df9"
},
"tracker": {
"trackerId": "26148317-7502-d3ac-44a9-546d240ac0dd",
"trackingNumber": "S24DEMO456393"
},
"shipment": {
"shipmentId": "f4f888d7-d140-423f-9a48-e0689d27e098",
...
},
"events": [ // The events object always contains one event at a time. Its length is always 1.
{
"eventId": "ee8ebe96-4eae-4a91-9a99-8f3afa6a0f46",
"status": "Delivered to the addressee",
"occurrenceDatetime": "2021-03-04T17:12:57",
...
}
]
...
}
}
]
}
Example with a maximum number of updates per webhook message above "1"
{
"trackings": [ // The trackings object contains tracking results for multiple shipments. Its length can be more than 1.
{ // Tracking update about a first shipment.
"metadata": {
"generatedAt": "2021-03-04T18:12:39.052Z",
"messageId": "356a7f93-3ce5-4b49-b560-156537283df9"
},
"tracker": {
"trackerId": "26148317-7502-d3ac-44a9-546d240ac0dd",
"trackingNumber": "S24DEMO456393"
},
"shipment": {
"shipmentId": "f4f888d7-d140-423f-9a48-e0689d27e098",
...
},
"events": [ // The events object always contains one event at a time. Its length is always 1.
{
"eventId": "ee8ebe96-4eae-4a91-9a99-8f3afa6a0f46",
"status": "Delivered to the addressee",
"occurrenceDatetime": "2021-03-04T17:12:57",
...
}
],
...
}
},
{ // Tracking update about a second shipment, containing a first event
"metadata": {
"generatedAt": "2021-02-03T13:12:25.010Z",
"messageId": "356a7f93-3ce5-4b49-b560-156537283dd5"
},
"tracker": {
"trackerId": "cf9f566a-493b-d686-41f3-b085bb4e429f",
"trackingNumber": "S24DEMO987452"
},
"shipment": {
"shipmentId": "9c2c13e9-dbc6-f79f-4199-693aadaa9ee0",
...
},
"events": [ // The events object always contains one event at a time. Its length is always 1.
{
"eventId": "e726b49a-bea6-26a8-4610-553548ca765b",
"status": "Arrived in destination country",
"occurrenceDatetime": "2021-02-03T12:17:00",
...
}
],
...
}
},
{ // Tracking update about the same second shipment, containing a second event
"metadata": {
"generatedAt": "2021-02-03T13:12:25.010Z",
"messageId": "248e5a70-278a-4d50-951d-e7c63f8c51c5"
},
"tracker": {
"trackerId": "cf9f566a-493b-d686-41f3-b085bb4e429f",
"trackingNumber": "S24DEMO987452"
},
"shipment": {
"shipmentId": "9c2c13e9-dbc6-f79f-4199-693aadaa9ee0",
...
},
"events": [ // The events object always contains one event at a time. Its length is always 1.
{
"eventId": "bbc4af45-9c99-749b-4945-e3211568ddb7",
"status": "In transit",
"occurrenceDatetime": "2021-02-02T20:10:00",
...
}
],
...
}
}
]
}
Webhooks Ordering
By definition, webhook messages are not guaranteed to arrive and be processed in order. If a webhook message fails and is retried later on, or if event information is provided at different times by couriers concerning one shipment, it is entirely possible to receive webhook messages in an order different from the event's physical occurring date.
Therefore, when processing a webhook message, you should always compare the event occurrenceDatetime from the message with the latest occurrenceDatetime from the events you already have before triggering any change of status or similar business rules, as the event from the webhook message may be older than an already imported event.
Webhooks Retries
In case Ship24 doesn't receive an HTTP status code in the 2xx range to a webhook request, the request will be retried up to 20 times with an exponential backoff, ranging from a few seconds to a few hours.
Webhooks Outgoing IPs
If your infrastructure or system restricts the reception of requests from public IPs, please allow all the following IPs:
3.222.254.22354.161.7.2
When initially setting your webhook URL in your Dashboard or using Test your integration, the request will NOT be coming from those IPs, which will cause an error at that stage. Please set up your webhook URL before applying IPs restriction, or contact us so we can set it up manually for you.