Skip to content
English
Submit a Ticket
Community forum
  • There are no suggestions because the search field is empty.

Technical Documentation For ShipWise Webhooks 

This webhook allows third-party systems to receive updates on shipments or tracking statuses. The webhook will post data to a specified endpoint whenever there is an update related to shipment tracking. The data payload contains shipment tracking details, status information, and timestamps. To ensure secure communication, the webhook includes a SHA256 hash value as an additional parameter for authentication

Endpoint

The webhook will POST data to the following endpoint:

POST https://your-webhook-endpoint.com/trackingUpdate

Payload

The payload is a JSON object containing the following fields:

{

"AccountId": "STRING",

"Code": "STRING",

"Description": "STRING",

"EstimatedDeliveryDate": DATETIME,

"IntCode": "STRING",

"IntType": "STRING",

"LastUpdate": "2026-08-12T16:46:30.4870374Z",

"Location": "STRING",

"Name": "STRING",

"PackageId": "STRING",

"ProofOfDeliveryImages": "STRING",

"ShipDate": "2026-08-12T16:46:30.4870374Z",

"Status": INTEGER,

"StatusName": "STRING",

"TimeStamp": "2026-08-12T16:46:30.4870374Z",

"TimeStampStr": "08/12/2026 16:46:30 UTC",

"TrackingActivityHistories": Object,

"TrackingNumber": "875683771667"

}

Field Descriptions

  • **accountId**: A string representing the unique identifier for the account associated with the shipment.
  • **trackingNumber**: The tracking number for the shipment.
  • **intCode**: A string representing an internal code associated with the shipment status. - **intType**: A string representing the type of internal code, typically indicating whether it is a status or event type.
  • **name**: The name of the shipment event or status.
  • **description**: A detailed description of the shipment event or status.
  • **location**: The location where the event occurred.
  • **code**: An external code representing shipment status.
  • **status**: A numeric status code where different numbers represent different statuses (e.g., 0 for in transit, 1 for delivered).
  • **statusName**: A human-readable name of the shipment status.
  • **timeStamp**: The exact time when the event occurred, formatted as an ISO 8601 string.
  • **timeStampStr**: A string version of the timestamp.
  • **lastUpdate**: The last time the shipment status was updated.
  • **estimatedDeliveryDate**: The estimated delivery date of the shipment (if available).
  • **shipDate**: The date when the shipment was initially dispatched.
  • **PackageId**: A string PackageID of the Shipment
  • **ProofOfDeliveryImages**: Proof of delivery images (if supported by carrier)
  • ** TrackingActivityHistories**: Object that contains pervious tracking events for the package.

 

Authentication

To ensure that the webhook is secure, a SHA256 hash is generated and included in the `x-shipwise-signature` field of the header.

Generating the Hash

 

  1. **Concatenate the Payload:** Convert the JSON payload  to a string.
  2. **Append the Secret Key:** Concatenate this string with a shared secret key known only to your server and the webhook provider. This will be generated in ShipWise when the endpoint is configured.
  3. **Generate the Hash:** Use the SHA256 algorithm to hash the resulting string.
  4. **Include the Hash:** Add the generated hash value to the `hash` field in the JSON payload.

 

Example:

 

```python import hashlib import hmac import json

secret_key = "your_secret_key" payload = {

"accountId": "string",

"trackingNumber": "string",

"intCode": "string","intType": "string",

"name": "string",

"description": "string",

"location": "string",

"code": "string",

"status": 0,

"statusName": "string",

"timeStamp": "2024-08-26T20:34:34.720Z",

"timeStampStr": "string",

"lastUpdate": "2024-08-26T20:34:34.720Z",

"estimatedDeliveryDate": "string",

"shipDate": "2024-08-26T20:34:34.720Z"

}

payload_str = json.dumps(payload) hash_value = hmac.new(secret_key.encode(), payload_str.encode(), hashlib.sha256).hexdigest() payload["hash"] = hash_value

headers = {

"Content-Type": "application/json"

"X-ShipWise-Signature": SignatureHash

}

Example Request

Here’s what an example request might look like:

HTTP POST /trackingUpdate HTTP/1.1

Host: your-webhook-endpoint.com

Content-Type: application/json

{

"AccountId": "203xxxxx",

"Code": null,

"Description": null,

"EstimatedDeliveryDate": null,

"IntCode": "F92",

"IntType": "F",

"LastUpdate": "2026-08-12T16:46:30.4870374Z",

"Location": null,

"Name": null,

"PackageId": "xxxxxxxxxx",

"ProofOfDeliveryImages": null,

"ShipDate": "2026-08-12T16:46:30.4870374Z",

"Status": 1,

"StatusName": "Created",

"TimeStamp": "2026-08-12T16:46:30.4870374Z",

"TimeStampStr": "08/12/2026 16:46:30 UTC",

"TrackingActivityHistories": null,

"TrackingNumber": "87xxxxxxxxxxxx"

}

Error Handling

If the webhook encounters an error (e.g., the `hash` value does not match or the payload is malformed), the receiving system should respond with an appropriate HTTP status code (e.g., 400 Bad Request) and a descriptive error message.

Expected Response

 

  • **200 OK**: If the payload is processed successfully.
  • **4XX Client Error**: If there is an issue with the request (e.g., bad hash, malformed JSON).
  • **5XX Server Error**: If there is an internal error on the receiving server.

 

This webhook documentation outlines how to post shipment tracking status updates to a third-party system securely using a SHA256 hash-based authentication mechanism. Make sure the receiving system verifies the `hash` value to maintain the integrity of the data.