1. Trackings
  • Introduction
  • Getting Started
  • Authentication
  • Error Handling
  • Contact Support
  • Modaltrans API
    • Get Auth Token
      • Get Bearer Token
    • Accounting
      • Invoices
        • Retrieve an Invoice
        • List all Invoices
      • Invoice Items
        • List all Invoice Items
        • Deleted Invoice Items
      • Financials
        • Retrieve Financial Information
    • Customs
      • NCTS Declarations
        • List all NCTS Declarations
        • Retrieve an NCTS Declaration
        • Create an NCTS Declaration with XML Data
        • Update an NCTS Declaration
        • Download an NCTS Declaration
        • List Timelines of NCTS Declaration
        • List Messages of NCTS Decalaration
      • Customs Declarations
        • List all Customs Declarations
        • Retrieve a Custom Declaration
        • Create a Customs Declaration
        • Update a Custom Declaration
        • Delete a Custom Declaration
        • Retrieve a Declaration History
        • Retrieve an MRN Status of Declaration
      • Declaration Requests
        • List all Declaration Orders
        • Retrieve a Declaration Request
        • Create a Declaration Request
        • Update a Declaration Request
        • Delete a Declaration Request
      • Ens Declarations
        • Create an Ens Declaration
        • Download an Ens Declaration
    • Logistics
      • Bookings
        • Retrieve a Booking
        • List all Bookings
        • Create a Booking
        • Update a Booking
      • Locations
        • List all Locations
        • Retrieve a Location
      • Positions
        • Update a Transport
        • Get All Positions
        • Retrieve a Position
      • Tracking
        • Available Shipping Lines
        • Retrieve a Tracking Data
        • Subscribe to Tracking
      • Shipments
        • Retrieve a Shipment
        • List All Shipments
        • Retrieve Financials of Shipment
        • List Contacts of the Shipment
        • Create a Shipment
        • Update a Shipment
      • Tariffs
        • List All Tariffs
        • Retrieve a Tariff
        • Create a Tariff
        • Update a Tariff
    • Depot
      • Orders
        • Retrieve an Order
        • List all Orders
        • Create an Order
        • Update an Order
      • Products
        • Retrieve a Product
        • List all Products
        • Create a Product
        • Update a Product
        • List Product Stocks
      • Inventories
        • List all Inventories
    • Fleet Management
      • Drivers
        • Retrieve a Driver
        • Retrieve a Driver's Vehicle
        • List Driver Positions
        • Update a Driver
      • Vehicles
        • Retrieve a Vehicle
        • Update a Vehicle
      • Gps Service Controller
        • Create Gps Responses
      • Service Logs
        • List all Service Logs
        • Retrieve a Service Log
        • Create a Service Log
        • Delete a Service Log
        • Update a Service Log
      • Periodic Documents
        • Retrieve a Periodic Document
        • Update a Periodic Document
        • Create a Periodic Document
    • CRM
      • Companies
        • List all Companies
        • Retrieve a Company
        • Create a Company
        • Update a Company
        • Delete a Company
        • List Company Credit Limits
      • Quotes
        • Retrieve a Quote
        • List All Quotes
        • Update a Quote
        • Create a Quote
        • Accept a Quote
        • Reject a Quote
    • Timelines
      • Retrieve a Timeline
      • List Timelines
      • Create a Timeline
    • S3 Files
      • List all S3Files
      • Create an S3File
      • Delete an S3File
    • Notifications
      • List all Notifications
      • Update a Notification Status
    • User Details
      • List User Details
      • Update User Details
    • Milestones
      • Retrieve a Milestone
      • List Milestones
      • Create a Milestone
      • Delete a Milestone
      • Update a Milestone
  • Webhooks
    • Webhooks
    • Trackings
      • Tracking Webhooks
      • Sea
        • Sea Tracking Event Created
        • Sea Tracking Event Updated
      • Air
        • Air Tracking Event Created
        • Air Tracking Event Updated
    • Customs
      • Customs Declaration Status Changed
      • NCTS Declaration Status Changed
      • ENS Declaration Status Changed
      • GVMS Declaration Status Changed
  1. Trackings

Tracking Webhooks

Tracking events reach you as they happen: a new carrier event on one of your sea shipments or air waybills, or a change to one you already received.
How an endpoint is created, how to check the signature, how to answer and what we retry is the same for every Modaltrans webhook and is described on the Webhooks page. This page covers what the tracking events carry and how far to trust each field.

Events#

Sea and air are separate subscriptions with separate payloads. Subscribe to either or both.
EventSent when
sea_tracking_events/createA new event is recorded against one of your sea shipments
sea_tracking_events/updateA sea event you already received changes
air_tracking_events/createA new status is recorded against one of your air waybills
air_tracking_events/updateAn air status you already received changes
Each page above carries the headers, the full payload schema and a worked example.
Sea events follow the DCSA container standard; air events follow the IATA status codes airlines already publish. The envelope, the headers, the signature and the retry behaviour are identical for both.

When an update is sent#

An update is only sent when something you can see actually changed: the event date, the estimated or actual flag, our normalised status, the status code the carrier published or its description, the location code or name, the terminal, the voyage or flight number, the vessel name or IMO number, or the container. Carriers restate unchanged events on every poll and we do not forward those.
What is watched is the event itself. Fields that come from the shipment rather than the event, such as the bill of lading and booking numbers, the air waybill number, the carrier code and the loading reference, can change without any update being sent, so take those from the next event that arrives rather than treating the first one as final. The same goes for the vessel position on sea events: it is read when the event is sent, and the vessel moving does not trigger an update on its own.

Matching events to your own records#

modaltrans.eventKey is the handle for the event as Modaltrans holds it, and it is what an update refers to. Two things to know before you build on it.
When a carrier restates a movement with a different timestamp or a different status code, we record it as a new event with a new key, and we never send deletions, so the earlier one stays on your side looking valid. Going the other way, two movements a carrier reports with the same status code at the same place can end up sharing one key, and you will see an update where you expected a second event. If either shape matters to you, key your own records on shipment plus status plus time and treat a changed timestamp as a correction of the closest match rather than as a new movement.
An update can also arrive for an event you never received a create for, for example on a shipment that was already running when the endpoint was created. Treat an update for an unknown eventKey as a create.

Status codes we emit#

Sea. The DCSA codes are mapped from our own normalised status, which travels with every event as modaltrans.systemStatus. Different carrier integrations report the same movement with different wording, so one DCSA code can come from several values.
equipmentEventTypeCodeemptyIndicatorCodemodaltrans.systemStatus
GTOTEMPTYgateOutWithContainerEmpty, empty_gate_out
GTOTLADENgateOutWithContainerFull, full_gate_out
GTINEMPTYgateInWithContainerEmpty, empty_gate_in
GTINLADENgateInWithContainerFull, full_gate_in
LOADLADENloadOnVessel, loadOnVesselAtTransitPort, load_on_vessel, and loadOnTruckContainerFull with modeOfTransport: TRUCK
DISCLADENdischargeFromVessel, dischargeToTransitPort, vessel_discharge
DROPLADENdeliveredToConsignee, delivered
transportEventTypeCodemodaltrans.systemStatus
DEPAvesselDepartureWithContainer, vessel_departure, vessel_departure_from_ts
ARRIberthingWithContainer, vesselArrivalWithContainer, vesselArrivalToTransitPort, vesselArrivalAtTransitPort, vessel_arrival, vessel_arrival_to_ts
Any sea event whose status is not in this table is not forwarded at all. Nor is an event without a date, or a sea event that is not linked to a container in Modaltrans.
A transhipment leg is not distinguishable from a DCSA code alone. Use modaltrans.systemStatus when you need to tell a transit port apart from the final port.
Vessel departures and arrivals (DEPA, ARRI) describe the vessel, not the box, so they carry no container number. On a consolidated position, where several house bills share one vessel booking, documentReferences is left out as well. On those events the only correlation handle is modaltrans.loadingReference, so store it from the first event of a shipment and key on it.
Air. statusCode is the IATA Cargo-IMP FSU code the airline published, trimmed and upper-cased. statusDescription is our own plain-English wording for that code; the airline's own text, when there is one, is in modaltrans.carrierEventDescription.
CodeMeaningCodeMeaning
BKDBookedRCFReceived from flight
RCSReceived from shipperRCTReceived from carrier
PREFreight preparedTFDTransferred to carrier
FOHFreight on handNFDConsignee notified
FIWFreight in warehouseAWRArrival documentation received
FOWFreight out of warehouseAWDArrival documentation delivered
MANManifestedCRCReported to customs
DEPDepartedCCDCustoms cleared
INFIn flightDISDiscrepancy
ARRArrivedDLVDelivered
Any other code an airline sends is not forwarded. On air, prefer statusCode over modaltrans.systemStatus: eight of the twenty codes above (FIW, FOW, INF, RCT, TFD, CRC, CCD, DIS) never carry a normalised status at all, while the IATA code is on virtually every event.

What to expect from the data#

Sea and air only. We do not track road or rail movements, so no tracking webhook is sent for them.
No history. Deliveries start from the moment the endpoint is created and nothing earlier is replayed, so ask us if you need a one-off backfill. Shipments that were already running do keep moving, so you will receive update events for them without ever having seen the create.
Optional fields depend on the source. Measured on a sample of 400 real events in September 2026: on sea a UN location code was present on about 15%, a voyage number on about 21% and a vessel IMO number on about 36%; on air a flight number was present on virtually every event and an airport on about 60%. Empty values are omitted rather than sent as null, so write your receiver to expect any optional field to be absent.
The vessel position is a snapshot. On sea events, modaltrans.vesselPosition is the last position the vessel named on the event reported over AIS, as it stood when the event was sent, with its own positionDateTime. We refresh the position of the vessel currently carrying the shipment with each tracking poll, so it can be hours old, and older for a vessel out of AIS coverage. It is only present when the event carries a vessel IMO number and we hold a position for that vessel. On an event from an earlier leg, such as a feeder, it is where that vessel is now, not where your container is.
Timestamps are ISO 8601 with a Z suffix. Carriers that publish an offset are converted to UTC. A few publish local port time with no offset at all, and those are passed through as we received them, so treat an event that is a few hours out as a carrier quirk rather than a movement you missed.
Not everything comes from a carrier. Gate, depot and delivery movements are often recorded by our own operators instead. Those carry a date picked by hand, so the time of day is midnight rather than a real clock time, and the location is our internal gate or place code rather than a UN/LOCODE.
ACT and EST do not always come from the carrier. Some carriers publish the flag themselves and we pass it on; for the rest we derive it from whether the timestamp is in the past. The payload does not tell you which of the two produced a given event, so treat ACT on a future date, or EST on a past one, as the carrier being quiet rather than as a contradiction.
Latency follows the source. Carriers are polled on a schedule, several times a day, so an event can reach you hours after it happened and longer overnight. We do not hold anything back once we have it.
Sea events follow DCSA Track and Trace 2.2. Air is outside that standard, since it has no container and no vessel, so air events carry the IATA Cargo-IMP FSU status code instead. Both shapes include a modaltrans object holding the values neither standard has a place for.
Modified at 2026-11-06 10:43:09
Previous
Webhooks
Next
Sea Tracking Event Created
Built with