Track: Carrier Integration Guide

Overview link

Sorted provides simplistic integration methods to enable Sorted carriers to submit their delivery events directly to our package tracking platform.

This enables carriers to provide structured and timely package tracking data to Sorted so that tracking events can be accurately recorded, providing retailers with real-time visibility and consistent package tracking across their delivery network.

This guide explains the integration methods and the data specifications of how a Sorted carrier should submit their package tracking data to us for processing.

To begin, please view the following:

• The prerequisites required to start the integration
• The data specification of what can be submitted to us; and
• The integration method you want to use to send your package tracking data

Prerequisites link

Before an integration can begin, carriers and Sorted must provide the following:

Carriers link

Carrier must provide us:

• Event codes
  Provide a complete list of your tracking event codes and descriptions. These will be mapped to Sorted’s standard tracking states to ensure consistent behaviour across the platform.

• Company logo
  A high-quality version of your logo, preferably SVG or PNG format with a transparent background.

• (Optional) Tracking URL
  A URL link to your website. This allows notifications to include an embedded link. Sorted will append the parcel number to this URL to create a direct link for customers.

Sorted link

Sorted will provide:

• Unique integration key
  A unique identifier that must be included in webhook submissions or used within the SFTP file naming convention. This ensures tracking data is correctly attributed and processed.

Data specification link

The following data specification is required for both Webhook and SFTP integration methods. Sample code and downloadable templates are available in each respective integration section below.

Tracking event fields link

Date Format Requirements link

All date/time fields must use ISO 8601 format including timezone offset.

Event sequencing link

For accurate tracking and correct behaviour, it is important to submit tracking events in the correct chronological sequence.

Sorted will always use the timestamp provided within the csv or json payload to determine the event order in the tracking timeline.

If events are provided out of sequence, Sorted may not trigger the expected state-change events and therefore associated triggers for webhooks or customer notifications may not be sent.

Final states link

Certain tracking states in our platform are considered final states. Once a shipment reaches a final state (e.g delivered), it cannot transition back to a previous operational state such as in_transit. Events attempting to move a shipment out of a final state will not trigger state changes. To view our mapped final states, please view the final state column of this table.

Integration methods link

1. Webhooks (Preferred) - See integration details below
2. SFTP (Batch File Transfer) - See integration details below

Webhook integration (preferred) link

Sorted carriers can POST their tracking events in JSON format to a Sorted endpoint using an integration key provided by Sorted to authenticate.

Webhook security link

To protect the integrity of tracking data submitted to Sorted, webhook integrations must be secured appropriately.

Sorted recommends a layered approach to webhook security, where multiple mechanisms are used together to reduce the risk of unauthorised or spoofed requests.

Security responsibilities link

Carriers are responsible for securing their webhook implementations and protecting any credentials used.

This includes:

• Storing keys and secrets securely
• Rotating credentials if they are exposed
• Preventing sensitive data from being logged or shared

Using stronger security mechanisms helps prevent unauthorised submissions, spoofed tracking events, and inaccurate tracking data being processed.

Webhook endpoint: link

    https://react.sorted.com/inbound/trackingevent/{UniqueIntegrationKey}
  

Example JSON Payload link

Please refer to the data specification section for full details of the required fields and data types.

  [
  {
    "code": "in_transit",
    "expected_delivery_date": "2025-01-28T17:00:00+00:00",
    "description": "At national hub",
    "timestamp": "2025-01-27T20:00:00+00:00",
    "reference": "TR-10012345678",
    "location": "West Midlands"
  },
  {
    "code": "out_for_delivery",
    "expected_delivery_date": "2025-01-28T17:00:00+00:00",
    "description": "On delivery vehicle",
    "timestamp": "2025-01-28T07:21:22+00:00",
    "reference": "TR-10012345678",
    "location": "Littleham depot",
    "delivery_slot": {
      "start": "2025-01-28T16:00:00+00:00",
      "end": "2025-01-28T18:00:00+00:00"
    }
  },
  {
    "code": "delivered",
    "description": "Delivery to customer",
    "timestamp": "2025-01-28T16:30:00+00:00",
    "reference": "TR-10012345678",
    "location": "Customer address",
    "signee": "J Smith",
    "lat_long": {
      "lat": 52.671397,
      "long": -2.098684
    }
  }
]
  

HTTP header validation (recommended for minimum security) link

Carriers should include a custom HTTP header with each webhook request. This acts as an additional authentication layer.

For example:

    X-API-Key: your-secure-key
  

Sorted will validate incoming requests against expected header values and reject any requests that do not match.

Signed payloads (recommended best practice) link

For enhanced security, carriers are strongly encouraged to implement signed webhook payloads.

Signed payloads ensure that:

• The request has been sent by a trusted source; and
• The message content has not been modified in transit

This is achieved by generating a cryptographic signature using a shared secret key and including it with each request.

Typical headers used in this approach include:

    X-Signature-Timestamp: <unix-timestamp>
  X-Signature: <signature>
  

Example (HMAC-SHA256)

  const crypto = require('crypto');

const secret = 'your-shared-secret';
const timestamp = Math.floor(Date.now() / 1000);
const body = JSON.stringify(payload);

// Create string to sign
const contentToSign = `${timestamp}.${body}`;

// Generate signature
const signature = crypto
  .createHmac('sha256', secret)
  .update(contentToSign)
  .digest('base64');

// Send headers with request
headers = {
  'X-Signature-Timestamp': timestamp,
  'X-Signature': signature
};
  

About SHA256 and HMAC link

SHA256 is a hashing algorithm that converts data into a fixed-length value. Even a small change in the input produces a completely different output.

HMAC-SHA256 combines this hashing algorithm with a secret key, ensuring that only parties with the shared secret can generate a valid signature. This allows Sorted to verify that the request is both authentic and unchanged.

SFTP integration (bulk method) link

Sorted carriers can alternatively submit tracking files via SFTP, with CSV and JSON file formats collected at regular intervals every 5–10 minutes.

The carrier is responsible for hosting the SFTP server and creating an account that Sorted can use to connect to. If required, Sorted can provide a set of static IP addresses to support IP whitelisting for inbound connections.

Example CSV & JSON formats link

Please refer to the data specification section for full details of the required fields and data types.

Download CSV template Download JSON example

Protocol, security and file management link

Our preference is to delete files immediately following successful download. If deletion is not possible (for example, due to a shared directory), we can support leaving files in place, in which case the Sorted carrier is responsible for clearing down old files.

link

Testing & Go-Live link

Prior to production go-live, carriers must:

• Complete integration testing
• Validate event mapping
• Submit sample tracking data; and
• Receive confirmation from Sorted that integration requirements have been met

Production access will only be enabled following a successful testing.