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.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.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.equipmentEventTypeCode | emptyIndicatorCode | modaltrans.systemStatus |
|---|
GTOT | EMPTY | gateOutWithContainerEmpty, empty_gate_out |
GTOT | LADEN | gateOutWithContainerFull, full_gate_out |
GTIN | EMPTY | gateInWithContainerEmpty, empty_gate_in |
GTIN | LADEN | gateInWithContainerFull, full_gate_in |
LOAD | LADEN | loadOnVessel, loadOnVesselAtTransitPort, load_on_vessel, and loadOnTruckContainerFull with modeOfTransport: TRUCK |
DISC | LADEN | dischargeFromVessel, dischargeToTransitPort, vessel_discharge |
DROP | LADEN | deliveredToConsignee, delivered |
transportEventTypeCode | modaltrans.systemStatus |
|---|
DEPA | vesselDepartureWithContainer, vessel_departure, vessel_departure_from_ts |
ARRI | berthingWithContainer, 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.| Code | Meaning | | Code | Meaning |
|---|
BKD | Booked | | RCF | Received from flight |
RCS | Received from shipper | | RCT | Received from carrier |
PRE | Freight prepared | | TFD | Transferred to carrier |
FOH | Freight on hand | | NFD | Consignee notified |
FIW | Freight in warehouse | | AWR | Arrival documentation received |
FOW | Freight out of warehouse | | AWD | Arrival documentation delivered |
MAN | Manifested | | CRC | Reported to customs |
DEP | Departed | | CCD | Customs cleared |
INF | In flight | | DIS | Discrepancy |
ARR | Arrived | | DLV | Delivered |
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.
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.
modaltrans object holding the values neither standard has a place for. Modified at 2026-09-25 15:25:45
