Webhook Payloads

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.

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

Getting Started

Tracking Fundamentals

Webhooks & Events

Integrations & Embeds

Platform & Reference

One notification per container

Notification envelope

Top-level fields

Reference object types

Included resources

Events with a minimal `included` array

Extracting common fields from `included`

Container update changesets

​One notification per container

​Notification envelope

​Top-level fields

​Reference object types

​Included resources

​Events with a minimal included array

​Extracting common fields from included

​Container update changesets

​Related

One notification per container

Notification envelope

Top-level fields

Reference object types

Included resources

Events with a minimal `included` array

Extracting common fields from `included`

Container update changesets

Related