Shipment tracking API for logistics and 3PL teams

Model a shipment cycle before importing a tracking number

Create one owned Trace shipment record per parcel cycle and save its returned ID in the TMS. order_id groups records; reference supplies an operational label. Tracking identity is immutable, so a replacement parcel or a closed monitoring cycle needs a new record rather than an identity edit.

For backfills, use the durable import API and reconcile per-row results. Import completion means records were created, not that carrier scans were retrieved. Keep your ingestion counters separate from verified-result counters so operators can distinguish a successful import from an upstream acquisition problem.

Acknowledge webhooks only after durable acceptance

Configure a final public HTTPS receiver URL. Redirects and login pages are integration failures, not an accepted event. Verify the exact raw request bytes with the signing secret and validate the timestamp/header contract before using the body.

The official TypeScript helper handles supported multiple v1 signatures during secret-rotation overlap. After verification, atomically deduplicate the event_id and enqueue or store the event. Return 2xx only after that durable acceptance. A console log followed by 200 can lose a business update when the process exits.

import express from 'express';
import { verifyWebhook } from '@traceapi/sdk';
const app = express();
app.post('/trace-events', express.raw({ type: 'application/json' }), async (req, res) => {
  const secret = process.env.TRACE_WEBHOOK_SECRET;
  if (!secret) return res.sendStatus(503);
  const signature = req.get('Trace-Signature') || '';
  const timestamp = signature.split(',').find(p => p.startsWith('t='))?.slice(2);
  if (req.get('Trace-Timestamp') !== timestamp ||
      !verifyWebhook(req.body, signature, secret)) return res.sendStatus(401);
  let event;
  try { event = JSON.parse(req.body.toString('utf8')); }
  catch { return res.sendStatus(400); }
  if (typeof event?.event_id !== 'string' ||
      event.event_id !== req.get('Trace-Event-Id')) return res.sendStatus(400);
  // Implement a DB transaction: UNIQUE event_id + durable queue insertion.
  try { await acceptOnce(event.event_id, event); }
  catch { return res.sendStatus(503); }
  return res.sendStatus(204);
});
// Register other JSON routes after this raw-body receiver.

Make retries, replay and reconciliation distinct

Automatic webhook retries address transient receiver failure within Trace’s delivery policy. Explicit replay is an operator decision for a finished event and preserves the event ID. It requires a reason and is limited to 60 requests per hour per account. Your consumer must remain idempotent during either path.

A read of the current shipment record can reconcile missed state, while immutable events provide observed scan history. Do not assume a webhook’s arrival time is a carrier’s scan time. Store receipt time separately, preserve source timestamps and avoid converting an offset-free timestamp into a fabricated UTC instant.

For example, after a TMS outage you might inspect failed attempts, recover the receiver, replay the relevant finished deliveries, and finally compare the local record projection with Trace’s current records. That sequence is more useful than repeatedly creating new webhook destinations.

Use evidence to organize the exception queue

Keep carrier-reported exceptions separate from Trace’s no-recent-scan inference. The alert includes kind so the operator can see what is reported by a source and what is derived by a rule. Acknowledging an alert records attention; it does not resolve the carrier condition.

Assign ownership and next actions in the TMS: contact the carrier, request missing clearance information, or review address instructions. Your rules should consider contractual service promises and the carrier’s authoritative records before triggering refunds, reshipments or claims. Trace’s normalized events are investigation evidence rather than a financial decision engine.

Evaluate reliability with cohort and recovery tests

Test active, delivered, exception and no-data parcels across your actual lanes. Include receiver 401, redirect and transient 5xx cases in a staging environment, then verify that duplicate events do not duplicate TMS actions. Keep production receiver tests deliberate because they cause an external delivery.

Merchant analytics can group your own records by carrier and destination and export CSV. Duration medians use eligible verified UTC histories and disclose exclusions; they are not contractual transit SLAs or unbiased carrier rankings. Measure verified-event success and event-recovery completeness separately from API service readiness.

• Check tenant ownership in every application-facing record lookup.
• Budget for successful background refreshes and keep bounded fallbacks when sources fail.
• Record request IDs and delivery IDs for support without copying unnecessary customer data into logs.
• Document a runbook for paused endpoints, secret rotation and shipments that reach the monitoring window’s end.

Common questions

References & next steps

Implementation details were checked against Trace’s current API. External product details may change; verify the linked documentation before deciding.

• Trace webhook history, replay and signing contract
• Trace analytics methodology