The Cargo Insight Webhook automatically delivers shipment tracking updates from SeaVantage to the customer’s configured endpoint whenever relevant tracking information is updated. This enables customers to keep their internal systems synchronized with the latest shipment data and automate downstream workflows without repeatedly calling the Cargo Insight API.

Webhook requests can be authenticated using either Basic Authentication or HMAC-SHA256, depending on the customer’s integration requirements.

Access to the webhook function is granted upon request. Please contact sales@seavantage.com to request access and begin the integration process.

Webhook Integration Flow

When Cargo Insight tracking information is updated, SeaVantage sends the updated data to the endpoint registered by your organization through an HTTP POST request.

Endpoint Requirements

The receiving endpoint must:

Accept HTTPS POST requests.

Authenticate requests using Basic Authentication or HMAC-SHA256, according to the configured authentication method.

Process the JSON payload included in the request body.

Check the eventId to prevent duplicate event processing.

Return an HTTP 2xx status code when the webhook request has been successfully processed.

Webhook Integration Set-up

1. Choosing an Authentication Method

Webhook requests must be authenticated to ensure that your system can verify requests sent by SeaVantage. SeaVantage and your organization will agree on one of the following authentication methods before proceeding with the integration setup.

Option A: Basic Authentication	Option B: HMAC-SHA256
SeaVantage uses the username and password provided by your organization to create the standard HTTP Authorization header for each request. Your receiving system verifies the credentials before accepting and processing the webhook request.	SeaVantage signs each webhook request using HMAC-SHA256 and the shared secret. Your system calculates the same signature and compares it with the Seavantage-Signature header to verify the request and signed data.

2. Integration Set-up Requirements

To configure webhook access, SeaVantage requires information about your receiving system and preferred authentication method. All required integration details should be submitted to sales@seavantage.com for configuration.

2.1 Required Information

Please provide the following information for the webhook configuration.

Item	Description
Company Name	Organization receiving the webhook
Technical Contact	Name and email address of the person responsible for the integration
Endpoint URL	Externally accessible HTTPS URL that will receive webhook requests Note: The endpoint must support HTTP POST requests.
Authentication Method	Select authentication method: 1. Basic Authentication 2. HMAC-SHA256

2.2 Basic Authentication

If Basic Authentication is selected as the authentication method, your organization must create and securely provide the credentials that SeaVantage will use in the request to your webhook endpoint. Please provide the following information:

Item	Description
Credential Delivery Method	Approved secure channel for securely providing the credentials to SeaVantage
Username	Username created by your organization for SeaVantage
Password	Password associated with the username

2.3 HMAC-SHA256 Authentication

If HMAC-SHA256 is selected as the authentication method, SeaVantage will generate the shared secret used to create and verify webhook signatures. Your organization must provide the authorized recipient and preferred secure delivery method for receiving the shared secret. Please provide the following information:

Item	Description
Secret Delivery Method	Approved secure channel through which SeaVantage should provide the shared secret
Authorized Recipient	Name and email address of the person authorized to receive the shared secret Note: Unless otherwise agreed, SeaVantage will generate the shared secret and provide it directly to the authorized recipient through the agreed secure delivery method.

2.4 Optional Information

The following information is optional and should be provided only if your organization requires specific endpoint or delivery configurations.

Item	Description
Endpoint Rate Limit	Maximum number of requests your endpoint can receive per minute or hour, if applicable
Retry Count	Number of retry attempts following an unsuccessful webhook delivery. Note: If no retry settings are specified, SeaVantage’s default settings of 3 attempts will apply.
Retry Interval	Time between each retry attempt Note: If no retry settings are specified, SeaVantage’s default settings of 10 minutes will apply.
Custom Headers	Additional HTTP headers that SeaVantage must include when sending requests to your endpoint

3. Network Access

During the integration setup, SeaVantage will provide the outbound IP address used to send webhook requests.

Add this IP address to the allowlist of your receiving system so that it can accept webhook requests from SeaVantage.

Webhook Request

1. Request Specifications

All webhook requests follow the specifications below:

Property	Value
HTTP Method	POST
Payload Format	JSON
Transport Security	HTTPS
Event ID Format	UUID

2. Request Headers

Webhook request headers vary depending on the authentication method configured for the integration. The following headers may be included:

Property	Value
Content-Type	application/json
Accept	application/json
User-Agent	seavantage-webhook/1.0
Webhook-Source	Always SeaVantage
Seavantage-Event-Id	Unique UUID-format identifier for the webhook event, used to prevent duplicate processing
Seavantage-Timestamp	Included when HMAC-SHA256 authentication is used
Seavantage-Signature	HMAC signature included when HMAC-SHA256 authentication is used
Authorization	Included when Basic Authentication is used

3. Example Request Headers

3.1 Basic Authentication

When Basic Authentication is configured, SeaVantage includes the Authorization header with each webhook request.

POST /webhooks/cargo?version=1 HTTP/1.1
Host: customer.example.com
Content-Type: application/json
Accept: application/json
User-Agent: seavantage-webhook/1.0
Authorization: Basic base64(username:password)
Webhook-Source: SeaVantage
Seavantage-Event-Id: <event-uuid>

{
  "documentId": "...",
  "containerNo": "..."
}
JSON
복사

3.2 HMAC-SHA256

SeaVantage generates a signature for each webhook request using the shared secret. Your system calculates the signature independently from the request it receives and compares the result with the `Seavantage-Signature` header. A matching signature confirms that the request was created using the shared secret and that the signed request data has not been modified.

Content-Type: application/json
Accept: application/json
User-Agent: seavantage-webhook/1.0
Webhook-Source: SeaVantage
Seavantage-Event-Id: <event-uuid>
Seavantage-Timestamp: 2026-07-15T01:23:45Z
Seavantage-Signature: v1=<base64-hmac-sha256>
JSON
복사

Property	Value
Algorithm	HMAC-SHA256
Signature encoding	Standard Base64
Signature format	v1=<base64-signature>
Canonical String encoding	UTF-8

4. Canonical String (for HMAC-SHA256 only)

The Canonical String is the exact string used to calculate and verify the HMAC signature. It is not sent as a separate request header or payload field. Your system must reconstruct the Canonical String from the received HTTP request.

4.1 Canonical String Format

Construct the Canonical String using the following format:

HTTP_METHOD + "\n" +
RAW_PATH_AND_QUERY + "\n" +
TIMESTAMP + "\n" +
EVENT_ID + "\n" +
RAW_BODY
JSON
복사

Each value must be separated by a single LF character (\n), and the values must be included in the exact order shown above.

4.2 Canonical String Fields

Field	Description
HTTP_METHOD	HTTP request method, normally POST
RAW_PATH_AND_QUERY	Request path and query string, excluding scheme and host
TIMESTAMP	Exact value of the Seavantage-Timestamp request header
EVENT_ID	Exact value of the Seavantage-Event-Id request header
RAW_BODY	Original request body exactly as received, without modification

4.3 Canonical String Example

Example Request

POST /webhooks/cargo?version=1 HTTP/1.1
Host: customer.example.com
Content-Type: application/json
Accept: application/json
User-Agent: seavantage-webhook/1.0
Webhook-Source: SeaVantage
Seavantage-Event-Id: 123e4567-e89b-12d3-a456-426614174000
Seavantage-Timestamp: 2026-07-15T01:23:45Z
Seavantage-Signature: v1=<base64-hmac-sha256>

{"status":"ARRIVED","containerNo":"SEGU1234567"}
JSON
복사

Canonical String

POST
/webhooks/cargo?version=1
2026-07-15T01:23:45Z
123e4567-e89b-12d3-a456-426614174000
{"status":"ARRIVED","containerNo":"SEGU1234567"}
JSON
복사

Escaped String Representation

POST\n/webhooks/cargo?version=1\n2026-07-15T01:23:45Z\n123e4567-e89b-12d3-a456-426614174000\n{"status":"ARRIVED","containerNo":"SEGU1234567"}
JSON
복사

4.4 Raw Body Handling

Use the original request body exactly as received when reconstructing the Canonical String and verifying the HMAC signature.

Do not modify the request body before signature verification. In particular, do not:

•

Parse and re-serialize the JSON.

•

Change the order of JSON fields.

•

Add or remove whitespace.

•

Modify line breaks.

•

Convert the body to a different character encoding.

For example, the following payloads contain the same data but have different raw representations, so they produce different HMAC signatures:

{"status":"ARRIVED","containerNo":"SEGU1234567"}
JSON
복사

{
  "containerNo": "SEGU1234567",
  "status": "ARRIVED"
}
JSON
복사

4.5 Raw Path and Query Handling

Use only the raw request path and query string when constructing the RAW_PATH_AND_QUERY component of the Canonical String.

Full URL

<https://customer.example.com/webhooks/cargo?version=1>
JSON
복사

Value included in the Canonical String

/webhooks/cargo?version=1
JSON
복사

Do not include the URL scheme or host:

<https://customer.example.com>
JSON
복사

5. Signature Verification (for HMAC-SHA256 only)

Your receiving system should verify the HMAC signature before processing the webhook payload.

Perform the following steps:

Read and preserve the raw request body.

Read the HTTP request method and raw path and query string.

Read the Seavantage-Timestamp header.

Read the Seavantage-Event-Id header.

Construct the Canonical String in the documented order.

Convert the complete Canonical String to UTF-8 bytes.

Calculate the HMAC-SHA256 digest using the shared secret.

Encode the resulting digest using Standard Base64.

Add the v1= prefix to create the expected signature.

10.

Compare the expected signature with the value of the Seavantage-Signature header.

Pseudocode

canonicalString =
    httpMethod + "\n" +
    rawPathAndQuery + "\n" +
    timestamp + "\n" +
    eventId + "\n" +
    rawBody

digest = HMAC_SHA256(
    key = sharedSecret,
    message = UTF8(canonicalString)
)

expectedSignature = "v1=" + STANDARD_BASE64(digest)
JSON
복사

Security Recommendation: Do not process the webhook payload if the Seavantage-Signature header is missing or the signature verification fails.

6. Response Handling

SeaVantage determines whether a webhook delivery was successful based on the HTTP response returned by your receiving system.

Code	Description
HTTP 2xx	The webhook delivery is considered successful.
Non-2xx response	The webhook delivery is considered unsuccessful and will be retried according to the configured retry policy.

7. Duplicate Event Handling

Each webhook event includes a unique UUID in the Seavantage-Event-Id request header. If duplicate event handling is required, your receiving system can use this value to identify and prevent duplicate processing of the same webhook event.

8. Webhook Payload

Each webhook request contains a snapshot of the tracking information for one cargo record at the time the webhook event was generated.

The webhook payload follows the same data structure as the response returned by the GET /cargo/search API, allowing the same field definitions and data model to be used for both API and webhook integrations.

8.1 Sample Webhook Payload

{
    "documentId": "string",
    "referenceType": "string",
    "carrierCode": "string",
    "bookingNo": "string",
    "mblNo": "string",
    "containerNo": "string",
    "blStatus": "string",
    "initialEtd": "2025-05-14 02:06",
    "initialEta": "2025-05-14 02:06",
    "bookingRegno": "string",
    "srNo": "string",
    "customColumn1": "string",
    "customColumn2": "string",
    "customColumn3": "string",
    "locations": [
      {
        "locationSeq": 0,
        "locationType": "string",
        "carrierLocationCode": "string",
        "carrierLocationName": "string",
        "carrierTerminalName": "string",
        "carrierEta": "2025-05-14 02:06",
        "carrierEtb": "2025-05-14 02:06",
        "carrierEtd": "2025-05-14 02:06",
        "carrierAta": "2025-05-14 02:06",
        "carrierAtb": "2025-05-14 02:06",
        "carrierAtd": "2025-05-14 02:06",
        "carrierShipName": "string",
        "carrierVoyageNo": "string",
        "ata": "2025-05-14 02:06",
        "atb": "2025-05-14 02:06",
        "atd": "2025-05-14 02:06",
        "pta": "2025-05-14 02:06",
        "imoNo": "string",
        "port": {
          "portId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
          "portName": "string",
          "unlocode": "string",
          "nationCode": "string"
          "timezone": "string"
        }
      }
    ],
    "hbls": [
      {
        "hblNo": "string",
        "ciNo": "1234567890",
        "shipperCode": "string",
        "shipperName": "string",
        "consigneeCode": "string",
        "consigneeName": "string",
        "ownerCode": "string",
        "ownerName": "string",
        "containers": [
          {
            "containerNo": "string",
            "hblNo": "string",
            "size": "string",
            "type": "string",
            "commodity": "string",
            "hscode": "string",
            "qty": 0,
            "gw": 0,
            "sealNo1": "string",
            "sealNo2": "string",
            "sealNo3": "string",
            "trackings": [
              {
                "shipName": "string",
                "imoNo": "string",
                "trackingSeq": 0,
                "eventCode": "string",
                "svEventDescription": "Empty Equipment Dispatched",
                "eventStatus": "string",
                "eventDescription1": "string",
                "eventDescription2": "string",
                "carrierEventTime": "string",
                "carrierLocationName": "string",
                "unlocode": "string",
                "locationType": "POR"
              }
            ]
          }
        ]
      }
JavaScript
복사

8.2 Detailed Payload Description

Depth 1 Field Description (response object)

Field	Example	Description	Data Type
documentId	6ebec210-a072-43ef-a6d1-874fddbc4b36	Internal unique cargo identifier	varchar(36)
carrierCode	CMAL	SCAC – 4-letter carrier code	varchar(10)
referenceType	MBL	Indicates which identifier was used when the cargo was initially registered for tracking. • CONTAINER: Registered using a container number • BOOKING: Registered using a booking number • MBL: Registered using a Master B/L number	varchar(16)
bookingNo	SHZ5400465	Booking number	varchar(512)
mblNo	SHZ5400465	Master Bill of Lading number	varchar(128)
containerNo	BEAU2789169	Container number	varchar(64)
blStatus	END	PROCESSING: Tracking is in progress after the tracking request is made. BEFORE: The vessel has not yet departed from the Port of Loading (POL), before ATD occurs. ON: The vessel has departed from POL and has not yet arrived at the Port of Discharge (POD). END: ATA has occurred at the POD (the vessel has arrived and berthed at the POD). PENDING: Location data is currently unavailable. NOT_FOUND: The system failed to retrieve tracking information for the shipment. CLOSED: Container tracking has ended after arrival at the POD. EXPIRED: The system continuously failed to retrieve tracking data during container tracking.	varchar(10)
initialEtd	2025-01-01 00:00	First collected ETD after cargo registration	timestamp
initialEta	2025-01-01 00:00	First collected ETA after cargo registration	timestamp
bookingRegno	null	Booking confirmation number	varchar(20)
srNo	null	Shipping request number	varchar(20)
customColumn1	null	Custom fields for clients	text
customColumn2	null	Custom fields for clients	text
customColumn3	null	Custom fields for clients	text
locations	[object Object]	Depth 2 → Refer to Location Fields
hbls	[object Object]	Depth 3 → Refer to HBL Fields

Depth 2 Field Description (locations object)

locations provide information about each port (Location) that the cargo passes through. For each location type (e.g., POL, POD), you can also check time-related details such as ETA/ETD, ATA/ATD and PTA.

Field	Example	Description	Data Type
locationSeq	0	Sequential order of each location within a partial shipment segment.	smallint
locationType	POL	POR: Place of Receipt POL: Port of Loading TSD: Transshipment Discharging TSL: Transshipment Loading POD: Port of Discharging PVY: Place of Delivery	varchar(20)
carrierLocationCode	CNSHK	Port code from carrier	varchar(5)
carrierLocationName	SHEKOU	Port name from carrier	varchar(200)
carrierTerminalName	CMA CGM PSA LION TERMINAL	Terminal name from carrier	varchar(200)
carrierEta	2025-01-01 00:00	Carrier’s Estimated Time of Arrival	timestamp
carrierEtb	2025-01-01 00:00	Carrier’s Estimated Time of Berthing	timestamp
carrierEtd	2025-01-01 00:00	Carrier’s Estimated Time of Departure	timestamp
carrierAta	2025-01-01 00:00	Carrier’s Actual Time of Arrival	timestamp
carrierAtb	2025-01-01 00:00	Carrier’s Actual Time of Berthing	timestamp
carrierAtd	2025-01-01 00:00	Carrier’s Actual Time of Departure	timestamp
carrierShipName	ANL WANGARATTA	Ship name from carrier	varchar(128)
carrierVoyageNo	0WWE9W1MA	Voyage number	varchar(32)
ata	2025-01-01 00:00	Actual Time of Arrival generated from SeaVantage Port Call data	timestamp
atb	2025-01-01 00:00	Actual Time of Berthing generated from SeaVantage Port Call data	timestamp
atd	2025-01-01 00:00	Actual Time of Departure generated from SeaVantage Port Call data	timestamp
pta	2025-01-01 00:00	Predicted Time of Arrival (SeaVantage proprietary data)	timestamp
imoNo	9334167	IMO Number	varchar(10)
port	[object Object]	Depth 3 → Refer to the port object

Depth 3 Field Description (port object)

Field	Example	Description	Data Type
portId	47941f60-13b8-4718-bead-aa7c3c61d530	SeaVantage internal port classification ID	varchar(36) - UUID
portName	Busan	Port name	varchar(255)
unlocode	KRPUS	Port UN/LOCODE	varchar(36)
nationCode	KR	Country code	varchar(36)
timezone	+09:00	Port timezone	varchar(36)

Depth 4 Field Description (hbls object)

hbls is an object that contains cargo information at the House B/L level. Multiple hbls can be associated with a single Master B/L; if none are entered, they will be generated automatically.

Field	Example	Description	Data Type
hblNo	SVH.SHZ5400465	House B/L No. If the value is system-generated (no House B/L is entered), it will automatically begin with SVH.	varchar(38)
ciNo	null	Commercial Invoice No.	varchar(50)
shipperCode	null	Shipper Code	varchar(20)
shipperName	null	Shipper Name	varchar(128)
consigneeCode	null	Consignee Code	varchar(20)
consigneeName	null	Consignee Name	varchar(128)
ownerCode	null	Cargo Owner Code	varchar(20)
ownerName	null	Cargo Owner Name	varchar(128)
containers	[object Object]	Depth 5 → Refer to the containers object

Depth 5 Field Description (containers object)

containers refers to an object that contains detailed information for each container included under a specific House B/L.

Field	Example	Description	Data Type
shipName	MSC CORDELIA III	Official registered name of the vessel	varchar(100)
imoNo	9253014	Ship’s 7-digit International Maritime Organization (IMO) registration number	varchar(10)
containerNo	BEAU2789169	Container Number	varchar(30)
hblNo	SVH.SHZ5400465	House B/L Number	varchar(38)
size	22	Container Size	varchar(16)
type	G1	Container Type Code	varchar(64)
commodity	null	Cargo Type	varchar(128)
hscode	null	HS Code (International Standard Commodity Code)	varchar(20)
qty	null	Quantity	numeric(14,3)
gw	null	Gross Weight	numeric(14,3)
sealNo1	null	Seal Number #1	varchar(64)
sealNo2	null	Seal Number #2	varchar(64)
sealNo3	null	Seal Number #3	varchar(64)
trackings	[object Object]	Depth 6 → Refer to trackings object

Depth 6 Field Description (trackings object)

trackings presents the event history that occurred for a container, where each object corresponds to a single event.

Field	Example	Description	Data Type
shipName	MSC CORDELIA III	Official registered name of the vessel	varchar(100)
imoNo	9253014	Ship’s 7-digit International Maritime Organization (IMO) registration number	varchar(10)
trackingSeq	0	Event sequence number per container	smallint
eventCode	EE	Event Code (See event code table below)	varchar(12)
svEventDescription	Empty Equipment Dispatched	SeaVantage standardized event description (See event code table below)	varchar(128)
eventStatus	Actual	Event status (Actual, Estimate)	varchar(20)
eventDescription1	EmptyDeliveredToShipper	Event description 1	varchar(512)
eventDescription2	TRUCK	Event description 2	varchar(512)
carrierEventTime	2025-01-01 00:00	Event timestamp	varchar(20)
carrierLocationName	SHEKOU	Location name where the event occurred	varchar(512)
unlocode	CNSHK	UN/LOCODE of the port where the event occurred	varchar(36)
locationType	POL	Location type where the event occurred POL: Port of Loading TS: Transshipment POD: Port of Discharging	varchar(20)

Appendix

Types of Container Event Codes

Event codes represent a container’s status, location, estimated time, and actual time.

Event Code	Description
EE	Empty Equipment Dispatched
I	In gate
AE	Loaded on vessel
VD	Vessel departure
VA	Vessel arrival
VB	Vessel berthing
UV	Unloaded from vessel
OA	Out gate
D	Delivered to the consignee
RD	Empty container returned
A	Arrived
AD	Appointment date/Time for delivery
AG	ETA Changed
AL	Loaded on rail
AM	Loaded on truck
AP	Loaded on feeder vessel
AR	Rail arrival at destination intermodal ramp
AV	Available for delivery
CO	Cargo received at contractual place of receipt
CR	Carrier release
CT	Customs released
CU	Carrier and customs released
FT	Free time expired
MT	Empty returned to CY
P	Full container issued
PA	Us customs hold
RL	Rail departure from original intermodal ramp
UR	Unloaded from rail
VE	Estimated vessel arrival
VT	Estimated vessel departure
X2	ETA at consignee location
C	Estimated to depart terminal location
CI	Passing
X6	En route to delivery location
R	Received from prior carrier
NO	Ocean charges paid
AW	Awaiting export
U	Unloading