Webhooks

UniUni can send webhook notifications to your server when shipment statuses change. Configure a webhook endpoint to receive shipment.status_updated events in real time.

Setup

To configure your webhook, provide the following to the UniUni team:

Field	Description
`endpoint`	HTTPS URL where you will receive webhook events
`authentication method`	`HMAC`, `Bearer`, or `None`
`hmacSecret`	Required only when using HMAC
`token`	Required only when using Bearer Token

Authentication methods

HMAC-SHA256 (Recommended)
Bearer Token
No Authentication

Webhook requests include an HMAC signature in the header:

X-Signature: <HMAC_SHA256(payload_body)>

Signature calculation:

signature = HMAC_SHA256(hmacSecret, JSON.stringify(payload))

Verification steps:

Read the X-Signature header
Recompute the signature using your secret
Compare using a timing-safe comparison

If the values match, the request is authentic.

Webhook requests include your token:

Authorization: Bearer <token>

Verification steps:

Read the Authorization header
Remove the Bearer prefix
Compare with the token you configured

If the values match, the request is valid.

For testing only — not recommended for production.

Content-Type: application/json

Anyone can call your endpoint when using this mode.

Payload format

Field	Type	Description
`event`	string	Event type (`shipment.status_updated`)
`data.trackingId`	string	Shipment tracking ID
`data.status`	string	New shipment status
`data.statusCode`	number	Internal status code
`data.updatedAt`	string	ISO 8601 timestamp
`data.address`	object	Address and location data
`data.proofOfDelivery`	object	Returned only when status is `DELIVERED`

Address

Field	Type	Description
`address1`	string	Address line 1
`address2`	string	Address line 2
`city`	string	City
`province`	string	Province / State
`postalCode`	string	Postal code
`country`	string	Country code
`latitude`	number	Latitude
`longitude`	number	Longitude

Proof of delivery

Included when the shipment status is DELIVERED.

Field	Type	Description
`recipient`	string	Name of person who received the parcel
`deliveryDate`	string	`YYYY-MM-DD`
`deliveryTime`	string	`HH:mm:ss`
`pods`	string[]	Proof of delivery image URLs

Example payload

{
  "event": "shipment.status_updated",
  "data": {
    "address": {
      "address1": "123 Main St",
      "address2": "Suite 100",
      "city": "Vancouver",
      "province": "BC",
      "postalCode": "V6B 1A1",
      "country": "CA"
    },
    "status": "DELIVERED",
    "statusCode": 203,
    "trackingId": "UR11170000000023641",
    "updatedAt": "2025-11-28T00:05:25.917Z",
    "proofOfDelivery": {
      "recipient": "John Doe",
      "deliveryDate": "2025-11-28",
      "deliveryTime": "00:05:25",
      "pods": [
        "https://delivery-service-api.uniuni.ca/images/abcd001",
        "https://delivery-service-api.uniuni.ca/images/abcd002"
      ]
    }
  }
}

Testing

Use the sandbox test endpoint to verify your webhook integration:

POST https://api-sandbox.ship.uniuni.com/webhook/test

This lets you validate that:

Your server receives webhook requests
Authentication is working correctly
Your system can parse the payload

Overview

Shipments

Batches

Labels

Tracking

Webhooks

Setup

Authentication methods

Payload format

Address

Proof of delivery

Example payload

Testing

Overview

Shipments

Batches

Labels

Tracking

Webhooks

​Setup

​Authentication methods

​Payload format

​Address

​Proof of delivery

​Example payload

​Testing

Setup

Authentication methods

Payload format

Address

Proof of delivery

Example payload

Testing