Every Terminal49 webhook delivery is a JSON:API document with a webhook_notification primary resource and related records in included.
Use this page as the payload reference. Use Payload Examples when you need complete sample JSON.
One notification per container
Container-scoped events fire once per container, not once per shipment or once per vessel move. If ten containers on the same vessel are discharged, you receive ten separate container.transport.vessel_discharged notifications — one for each container. Each payload references a single container through its reference_object and (when included) the container resource in included.
Use data.id on the notification as the idempotency key when deduplicating retries, and the container id or number to route each notification to the right record on your side.
Notification envelope
{
"data": {
"id": "87d4f5e3-df7b-4725-85a3-b80acc572e5d",
"type": "webhook_notification",
"attributes": {
"event": "container.updated",
"delivery_status": "pending",
"created_at": "2026-05-11T18:30:00Z"
},
"relationships": {
"webhook": {
"data": {
"id": "8a5ffa8f-3dc1-48de-a0ea-09fc4f2cd96f",
"type": "webhook"
}
},
"reference_object": {
"data": {
"id": "e8f1976c-0089-4b98-96ae-90aa87fbdfee",
"type": "container_updated_event"
}
}
}
},
"included": []
}
Top-level fields
| Field | Type | Description |
|---|
data.id | UUID | Unique webhook notification ID. Use this as the idempotency key. |
data.type | string | Always webhook_notification. |
data.attributes.event | string | Event name, such as tracking_request.succeeded or container.updated. |
data.attributes.delivery_status | string | Delivery state for this notification. Values include pending, succeeded, and failed. |
data.attributes.created_at | timestamp | Time Terminal49 created the notification. |
data.relationships.webhook | relationship | Webhook endpoint that received the notification. |
data.relationships.reference_object | relationship | Event-specific object that caused the notification. |
included | array | Related records included for convenience. Contents vary by event. |
Reference object types
| Event family | Common reference_object.type | Notes |
|---|
tracking_request.* | tracking_request | Includes the tracking request and, when available, shipment/container records. |
container.transport.* | transport_event | Includes the transport event, container, shipment, and location records that are available. |
shipment.estimated.arrival | estimated_event | Includes the estimate event and related shipment records. |
container.updated | container_updated_event | Includes a changeset describing changed container attributes. |
container.created | container_created_event | Includes the new container and related shipment. |
container.pickup_lfd.changed and the pickup_lfd_line / pickup_lfd_terminal / pickup_lfd_rail variants | transport_event | The transport event’s value attribute carries the new Last Free Day. The container with updated LFD fields may also be included, as in the container.pickup_lfd.changed example. |
document.* | document-related event resource | Available for accounts using document processing. See Document Processing Workflows. |
Included resources
Webhook payloads may include:
| Resource type | When included |
|---|
tracking_request | Included for tracking request lifecycle events and related shipment updates. |
shipment | Included when the event relates to a shipment or one of its containers. |
container | Included for container lifecycle, status, availability, and milestone events. |
transport_event | Included for container.transport.* milestone events and LFD or appointment change events. |
estimated_event | Included for ETA change events. |
container_updated_event | Included for container.updated events. |
port | Included when a payload references a port record. |
terminal | Included when a payload references a terminal record. |
vessel, rail_terminal, and metro_area — can appear for specific events. The webhook endpoint that received the delivery is referenced through the webhook relationship on the notification, not serialized in included.
Do not require every resource to be present. Carrier, terminal, and event data can arrive at different times.
Events with a minimal included array
A few events ship with only the reference object in included (or with an empty included array). The shipment and container records are not embedded in the payload:
container.transport.availablecontainer.transport.not_availablecontainer.transport.estimated.vessel_departedcontainer.transport.estimated.vessel_arrivedcontainer.transport.estimated.arrived_at_inland_destinationcontainer.pickup_appointment.changed
To resolve the container number or bill of lading number for these events, follow the reference_object relationship and fetch the related transport event, container, or shipment through the API — for example, Get a container using the container ID from the transport event’s relationships, or Get a shipment using the shipment ID.
For events that do include the related records, the fields most integrations pull are consistent across events:
| Field | Location in included |
|---|
| Event timestamp | Object with type: "transport_event" → attributes.timestamp |
| Estimated timestamp (ETA events) | Object with type: "estimated_event" or type: "transport_event" → attributes.timestamp (or attributes.estimated_timestamp on legacy estimated_event payloads) |
| Container number | Object with type: "container" → attributes.number |
| Bill of lading number | Object with type: "shipment" → attributes.bill_of_lading_number |
| Voyage number | Object with type: "transport_event" → attributes.voyage_number |
| Location UN/LOCODE | Object with type: "transport_event" → attributes.location_locode |
Container update changesets
For container.updated events, the event resource includes a changeset object. Each key is a changed field. The value is a two-item array: [previous_value, current_value].
{
"changeset": {
"pickup_lfd": [null, "2026-05-14T07:00:00Z"],
"available_for_pickup": [false, true]
}
}
fees_at_pod_terminalholds_at_pod_terminalpickup_lfdpickup_lfd_linepickup_lfd_railpickup_appointment_atavailable_for_pickuppod_terminal
The event’s timestamp attribute tells you when Terminal49 picked up the changes from the terminal.
For pod_terminal, the changeset values are terminal record IDs, not names:
{
"changeset": {
"pod_terminal": ["0ef5519f-3bde-4d1f-a327-f4f2d833dc7b", "08831e36-676a-4bd4-9c26-c8ab7dbfe73e"]
}
}
terminal resources serialized in included.
The container_updated_event also has a terminal relationship that indicates where the data came from. Currently this is always the POD terminal; in the future it may be the final destination terminal or an off-dock location.
