{"@context":"https://schema.org","@type":"TechArticle","headline":"TrackJet Verifiable Timeline specification","author":{"@type":"Organization","name":"TrackJet"},"about":"Tamper-evident shipment event timelines via SHA-256 hash-chains"} Skip to content
TrackJet
TrackJet

Language

Deutsch English Español

7-day Pro trial included with every new account — no card, no charge.

Start free with 500 saved shipments. Every new account also gets a 7-day Pro trial — no card required.

Start 7-day Pro trial

tjvt1 · specification

TrackJet Verifiable Timeline

A tamper-evident seal for shipment event histories. Every event is hashed into an append-only SHA-256 chain at the moment it is recorded; any later edit, reorder or deletion of past events breaks verification. Check any tracked chain at /verify.

Construction

h(0) = SHA256( "tjvt1:" || shipment_uuid || ":" || primary_tracking )
h(n) = SHA256( h(n-1) || canonical(event_n) )          n = 1..N

canonical(event) is deterministic JSON with this exact key order, no insignificant whitespace, unescaped UTF-8 and slashes: 

{"v":"tjvt1","seq":<n>,"leg_order":<int>,"occurred_at":"<RFC3339>",
 "status":"<string>","description":"<string>","location":<string|null>,
 "country_code":<string|null>}

Events are ordered by (occurred_at, leg_order, ingest index) — the same stable order the timeline UI renders. seq binds each event to its position, so swapping two otherwise-identical events also breaks the chain.

What a valid result proves — and what it doesn't

  • Proves: the event history stored today is byte-identical to what TrackJet recorded at ingest time — nothing was edited, reordered or deleted afterwards.
  • Does not prove: that the carrier's original data was correct. The seal covers TrackJet's record from the moment of ingest, not reality before it.
  • Seals are written after the database commit, append-only. Events that arrived seconds ago can be briefly unsealed ("unsealed tail") — that is reported as such, not as tampering.
  • The verifier and the proof API expose integrity metadata only (validity, counts, digests) — never event contents.

Programmatic access

  • GET /api/v1/shipments/{uuid}/proof — seal list (hashes only) + verification verdict (API key required; see API docs).
  • MCP tool verify_timeline — same verdict for AI agents (MCP docs).

Spec version tjvt1 · hash function SHA-256 · published 2026-06-10. Changes to the canonical form will bump the version prefix; existing seals remain verifiable under their original version.