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 webhook you receive, please contact us to update this setting.

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.
    {
      "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 updates for multiple shipments. Its length can be more than 1.
    { // Tracking update about a first shipment.
      "tracker": {
        "trackerId": "26148317-7502-d3ac-44a9-546d240ac0dd",
        "trackingNumber": "S24DEMO456393"
      },
      "shipment": {
        "shipmentId": "f4f888d7-d140-423f-9a48-e0689d27e098",
        ...
      },
      "events": [ // The events object contains multiple events for this shipment. Its length can be more than 1.
        {
          "eventId": "ee8ebe96-4eae-4a91-9a99-8f3afa6a0f46",
          "status": "Delivered to the addressee",
          "occurrenceDatetime": "2021-03-04T17:12:57",
          ...
        },
        {
          "eventId": "ee8ebe96-4eae-4a91-9a99-8f3afa6a00ja",
          "status": "Out for Delivery",
          "occurrenceDatetime": "2021-03-04T10:12:57",
          ...
        }
      ],
      ...
      }
    },
    { // Tracking update about a second shipment.
      "tracker": {
        "trackerId": "cf9f566a-493b-d686-41f3-b085bb4e429f",
        "trackingNumber": "S24DEMO456393"
      },
      "shipment": {
        "shipmentId": "9c2c13e9-dbc6-f79f-4199-693aadaa9ee0",
        ...
      },
      "events": [ // The events object contains multiple events for this shipment
        {
          "eventId": "e726b49a-bea6-26a8-4610-553548ca765b",
          "status": "Arrived in destination country",
          "occurrenceDatetime": "2021-02-03T12:17:00",
          ...
        },
        {
          "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.223
• 54.161.7.2

caution

When setting initially 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 set it up manually for you.