Webhook Payload Structure

Understand the data structure your webhooks receive from StarShipper

Last updated: August 2026

Overview

Webhooks fire per shipment. When a shipment is dispatched, StarShipper POSTs the whole shipment record as JSON to your configured endpoints: its references, routing, dates, totals, every container with its line items, every linked party, and metadata for the source documents. Fields are camelCase and sit at the top level, so there is no envelope and nothing to unwrap.

Important: By default, all extracted fields are sent. You can rename fields using field mapping in your inbox settings if your receiving system expects different field names.

What Data Gets Sent?

The shipment record, exactly as it goes on the wire

All extracted fields

Every field extracted by AI from the document

Document metadata

Filename, type, processing time, etc.

Email context

Sender info and subject line

Structured JSON

Easy to parse and integrate

Example Payload

A sample shipment payload

{
  "shipmentId": "3f9a2b18-5c47-4c1e-9a3d-7b6e0f2c8d41",
  "stage": "shipment",
  "organizationId": "b21c4e77-90aa-4f3b-8d52-1c6e9a04f7b3",
  "referenceNumber": "SS-2026-004182",
  "version": 3,
  "hblNumber": "AION0025518",
  "mblNumber": "MSCUZH492117",
  "bookingNumber": "BK-2026-001234",
  "invoiceNumber": "INV-88213",
  "customsReference": null,
  "mode": "SEA",
  "carrier": "MSC",
  "vesselName": "MSC AURORA",
  "voyageNumber": "025N",
  "originPort": "CNSHA",
  "originPortName": "Shanghai",
  "destinationPort": "AUBNE",
  "destinationPortName": "Brisbane",
  "etd": "2026-08-02",
  "eta": "2026-08-24",
  "atd": "2026-08-02",
  "ata": null,
  "shipmentDate": "2026-08-02",
  "invoiceDate": "2026-07-28",
  "goodsDescription": "Electronic components",
  "totalPackages": 500,
  "totalGrossWeight": 12500,
  "weightUnit": "KG",
  "totalVolume": 45,
  "volumeUnit": "CBM",
  "incoterm": "CIF",
  "invoiceAmount": 125000,
  "invoiceCurrency": "USD",
  "freightTerms": "PREPAID",
  "isHazardous": false,
  "carrierScac": "MSCU",
  "abn": "51824753556",
  "containers": [
    {
      "containerNumber": "MSCU1234567",
      "containerType": "40HC",
      "sealNumber": "SL889201",
      "grossWeight": 12500,
      "weightUnit": "KG",
      "lineItems": [
        {
          "lineNumber": 1,
          "description": "Electronic components",
          "quantity": 500,
          "quantityUnit": "CTN",
          "grossWeight": 12500,
          "weightUnit": "KG",
          "hsCode": "8542.31.00",
          "countryOfOrigin": "CN",
          "unitPrice": 250,
          "lineTotal": 125000
        }
      ]
    }
  ],
  "parties": [
    {
      "role": "shipper",
      "name": "Acme Manufacturing Co Ltd",
      "code": null,
      "abn": null,
      "address": {
        "line1": "1234 Industrial Park Road",
        "line2": null,
        "city": "Shanghai",
        "state": null,
        "postCode": "200000",
        "country": "CN"
      },
      "contact": {
        "name": null,
        "email": "export@acme-mfg.cn",
        "phone": null
      }
    },
    {
      "role": "consignee",
      "name": "Global Distributors Pty Ltd",
      "code": null,
      "abn": "51824753556",
      "address": {
        "line1": "5678 Commerce Drive",
        "line2": null,
        "city": "Brisbane",
        "state": "QLD",
        "postCode": "4000",
        "country": "AU"
      },
      "contact": {
        "name": null,
        "email": null,
        "phone": null
      }
    }
  ],
  "documents": [
    {
      "id": "8c1d5e90-2a34-4b7f-9e18-3d6a0c5b2f47",
      "filename": "BOL_AION0025518.pdf",
      "documentType": "ocean_bill_of_lading",
      "mimeType": "application/pdf",
      "fileSizeBytes": 184320,
      "contentHash": "b1f0c8a742e35d96ac0b3e5178d24fa9c6e07b5312d4a8f9e0c17b62d5a3049e",
      "createdAt": "2026-08-03T04:12:08.410Z"
    }
  ],
  "status": "in_transit",
  "customsStatus": null,
  "createdAt": "2026-08-03T04:12:08.410Z",
  "updatedAt": "2026-08-12T22:47:31.902Z"
}

Field Descriptions

Detailed explanation of each field in the payload

Field	Type	Description
shipmentId	string (uuid)	The shipment this send is about. Stable across every send for the same job.
stage	string	`order` before a booking is confirmed, `shipment` after.
referenceNumber	string	Your StarShipper reference for the job.
version	number	Increments on each dispatch of this shipment, so a receiver can discard an out-of-order delivery.
hblNumber / mblNumber	string \| null	House and ocean bill numbers.
bookingNumber / invoiceNumber	string \| null	Booking and commercial invoice references.
mode / carrier	string \| null	SEA, AIR, ROA, RAI, and the carrier name.
vesselName / voyageNumber	string \| null	Vessel and voyage where known.
originPort / destinationPort	string \| null	UN/LOCODE. The matching `*PortName` fields carry the readable name.
etd / eta / atd / ata	string \| null	Estimated and actual departure and arrival, ISO 8601 dates.
totalPackages / totalGrossWeight / totalVolume	number \| null	Totals for the job, with `weightUnit` and `volumeUnit` alongside.
incoterm / freightTerms	string \| null	Commercial terms.
invoiceAmount / invoiceCurrency	number \| null / string \| null	Declared value and its currency.
isHazardous / imoClass / unNumber	boolean / string \| null	Dangerous goods flags.
abn	string \| null	Australian Business Number where one has been resolved.
containers	array	One entry per container, each carrying its own `lineItems` array.
parties	array	One entry per linked party, with `role`, `name`, nested `address` and `contact`.
documents	array (optional)	Source document metadata only: id, filename, documentType, mimeType, fileSizeBytes, contentHash, createdAt. File bytes are never included.
status / customsStatus	string / string \| null	Current shipment and customs state.
createdAt / updatedAt	ISO 8601	When the shipment record was created and last changed.

Field Mapping

Rename fields to match your system's expected format

If your receiving system expects different field names, you can rename them using field mapping:

All fields sent by default: the whole shipment record goes out on every send, so you can ignore what you do not need
Rename Fields: Map StarShipper field names to your system's expected names
Configured per integration: mappings are held against the connection (and per doc-type schema where you have set one), so two endpoints can receive different field names for the same shipment

How to Handle Webhook Payloads

1
Create an endpoint on your server that accepts POST/PUT/PATCH requests
2
Parse the JSON payload from the request body
3
Read the fields you need from the top level of the body, or from the containers and parties arrays
4
Map to your system's fields - you control how data is mapped internally
5
Respond with HTTP 200 to confirm successful receipt

Setting Up Webhooks Docs Home