Webhook Payloads

Reference for the Terminal49 webhook notification envelope, JSON:API included resource patterns, and links to complete event payload examples.

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.

Other resource types — such as 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.available
• container.transport.not_available
• container.transport.estimated.vessel_departed
• container.transport.estimated.vessel_arrived
• container.transport.estimated.arrived_at_inland_destination
• container.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.

Extracting common fields from included

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 ID	Object with type: "container" → id
Container number	Object with type: "container" → attributes.number
pod_full_out_at, pod_arrived_at, pod_discharged_at, empty_terminated_at, pickup_lfd, available_for_pickup	Object with type: "container" → attributes.<field>
Shipment ID	Object with type: "shipment" → id
Bill of lading number	Object with type: "shipment" → attributes.bill_of_lading_number
Reference numbers (ref_numbers)	Object with type: "shipment" → attributes.ref_numbers
pod_eta_at, pod_original_eta_at, destination_eta_at, pod_ata_at	Object with type: "shipment" → attributes.<field>
Voyage number	Object with type: "transport_event" → attributes.voyage_number
Location UN/LOCODE	Object with type: "transport_event" → attributes.location_locode

ETA fields (pod_eta_at, pod_original_eta_at, destination_eta_at) and identifiers like bill_of_lading_number live on the shipment, not the container. If you only see container fields in a payload, look for the object with type: "shipment" in included. For a full mapping, see Which object holds which field?.

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]
  }
}

Common changed fields include:

• fees_at_pod_terminal
• holds_at_pod_terminal
• pickup_lfd
• pickup_lfd_line
• pickup_lfd_rail
• pickup_appointment_at
• available_for_pickup
• pod_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"]
  }
}

Resolve the IDs through the 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.

Related

• Event Catalog - canonical event names
• Payload Examples - complete sample JSON
• Set Up Webhooks - create and secure webhook endpoints
• Webhook Notifications API - inspect notification delivery status