Trace

Use case

Package tracking API for Logistics & 3PL

Logistics teams and 3PLs need tracking data flowing into their own systems, not another dashboard. The reliable pattern is a tracking API plus signed webhooks that push status changes as they happen.

Trace posts HMAC-signed webhooks for tracking.updated, tracking.delivered, and tracking.exception, so your TMS updates automatically without polling.

How it works

  1. 1Create a webhook destination in the Trace dashboard and choose the events you want.
  2. 2Expose an endpoint that verifies the Trace-Signature header (HMAC-SHA256).
  3. 3Update your internal shipment record when events arrive, and dedupe on Trace-Event-Id.

Express — verify and handle Trace webhooks

const crypto = require("node:crypto");

app.post("/trace-webhook", express.raw({ type: "application/json" }), (req, res) => {
  const header = req.headers["trace-signature"] || "";
  const match = /^t=(\d+),v1=([0-9a-f]+)$/.exec(header);
  if (!match) return res.status(401).end();

  const timestamp = match[1];
  const expected = crypto
    .createHmac("sha256", process.env.WEBHOOK_SIGNING_SECRET)
    .update(timestamp + "." + req.body.toString("utf8"))
    .digest("hex");

  const received = match[2];
  if (crypto.timingSafeEqual(Buffer.from(received), Buffer.from(expected))) {
    const event = JSON.parse(req.body);
    console.log(event.event_type, event.tracking.status);
    return res.status(200).end();
  }
  return res.status(401).end();
});

Logistics & 3PL FAQ

How do I verify webhooks are from Trace?

Check the Trace-Signature header: it's t=<timestamp>,v1=<hmac>. Compute HMAC-SHA256 of timestamp + raw body with your webhook secret.

Are webhooks delivered exactly once?

At least once. Delivery is retried, so dedupe on the Trace-Event-Id header.

What events can I subscribe to?

tracking.updated, tracking.delivered, and tracking.exception.

Start tracking for free.

Create an account, generate an API key, and track your first package in under two minutes — no credit card required.

Get your free API keyAll use cases