Gareth Wilson Gareth Wilson

Guide to Trackstar Webhooks: Features and Best Practices

Published


Trackstar puts one API in front of warehouse management systems, shopping carts, carriers and freight providers. Your customers connect their own WMS or cart, Trackstar syncs orders, inventory, shipments and products from it, and your application reads normalised data. Webhooks tell you when a synced resource changes and when a connection itself is created, deleted, stuck or broken.

AspectValue
MethodPOST, Content-Type: application/json
Signature headerssvix-id, svix-timestamp, svix-signature (Standard Webhooks; webhook-* carry the same values)
Event nameTop-level event_type
TimingResource events fire at the resource's sync frequency; none are sent during a connection's initial sync

What follows covers Trackstar's 47 events, how previous_attributes records a change, why nothing arrives during an initial sync, the Svix signature, and the gaps in Trackstar's delivery documentation.

What are Trackstar webhooks?

Trackstar uses Svix as its webhook provider. The Webhooks page of the Trackstar dashboard is a Svix portal, where you add endpoints, filter which messages they receive and attach JavaScript transformations. For signatures, Trackstar's webhooks guide links to Svix's manual verification page and adds nothing of its own; its AI-assistant guide names the svix-id, svix-timestamp and svix-signature headers.

Timing is tied to syncing. A resource event such as order.updated fires when Trackstar's next scheduled sync of that resource notices the change, not when the change happens in the WMS, so how quickly you hear about it depends on the resource's sync frequency.

Trackstar webhook features

FeatureDetails
SignatureStandard Webhooks HMAC-SHA256
Signature headersvix-signature
BodyJSON
Event routingBody field event_type
Delivery platformSvix
ConfigurationDashboard Webhooks page (Svix portal)
FiltersEvent type, connection ID, resource ID, date
TransformationsJavaScript, per endpoint
Change trackingprevious_attributes on updates
Secret formatNot printed (Svix issues whsec_)
Retries, timeout, orderingNot documented

Events and payloads

FieldDescription
event_typeThe event name, e.g. order.updated
connection_idThe connection the event came from
integration_nameThe integration (e.g. a WMS) the event came from
dataThe created or updated object
previous_attributesOnly on *.updated events: the previous values of the changed fields

A change inside a nested field is keyed by a .-joined path, where integers are array indexes and strings are object keys. In Trackstar's sample for an inbound shipment, the status moved from open to received and the second line item's received quantity from 1 to 2:

{
  "event_type": "inbound_shipment.updated",
  "connection_id": "connection_id",
  "integration_name": "integration_name",
  "data": {
    "id": "id",
    "status": "received",
    "line_items": [
      { "sku": "sku1", "expected_quantity": 1, "received_quantity": 1 },
      { "sku": "sku2", "expected_quantity": 2, "received_quantity": 2 }
    ],
    "updated_date": "2023-06-14T15:36:48Z"
  },
  "previous_attributes": {
    "status": "open",
    "line_items.1.received_quantity": 1
  }
}

That example is trimmed from Trackstar's, which has trailing commas and placeholder values, so it can't be parsed as published. The per-event pages don't carry usable schemas either.

Event names are not fully consistent. Most multi-word resources use a hyphen (inbound-shipment.updated, connection-error.created), but inventory_ledger.created uses an underscore, and Trackstar's own sample body writes inbound_shipment.updated. Match on the names in the list below, and let unknown names fall through to a 200.

Common Event Types

EventTriggered WhenCommon Use Cases
connection.createdA customer connects an integrationStart tracking the connection
connection.deletedA connection is deletedClean up stored credentials and data
connection.historical-sync-completedThe initial sync finishes for a resource typeStart reading data (it is now queryable)
connection.sync-job-stuckTrackstar decides a sync job won't progressAlert support
connection-error.createdA connection error is raisedPrompt the customer to reconnect
install.failedAn attempt to connect an integration fails before a connection existsShow an install error
order.createdAn order is created in the WMSIngest the order
order.updatedAn order changes (previous_attributes has the old values)Update status
order.shipment.createdA shipment is created for an orderSend tracking
inventory.updatedAn inventory item changesSync stock levels
inbound-shipment.updatedAn inbound shipment changesTrack receiving

Full Event List (47 documented)

  • Admin: install.failed, connection.created, connection.deleted, connection.historical-sync-completed, connection.force-sync-completed, connection.sync-job-completed, connection.sync-job-stuck, connection.schedule-stuck, connection-error.created, connection-error.updated, connection-error.deleted
  • WMS: bill.created, bill.updated, inbound-shipment.created, inbound-shipment.receipt.created, inbound-shipment.updated, inventory.created, inventory.updated, inventory_ledger.created, inventory_ledger.updated, order.created, order.shipment.created, order.updated, product.created, product.updated, return.created, return.updated, shipping-method.created, shipping-method.updated, warehouse-customer.created, warehouse-customer.updated, warehouse-location.created, warehouse-location.updated, warehouse.created, warehouse.updated
  • Cart: cart-order.created, cart-order.cart-shipment.created, cart-order.updated, cart-product.created, cart-product.updated, cart-warehouse.created, cart-warehouse.updated
  • Freight: freight-shipment.created, freight-shipment.updated
  • Carrier: carrier-file.created, carrier-invoice-line-item.created, carrier-invoice-line-item.updated

The list is taken from the webhook pages in Trackstar's docs and may not be exhaustive.

connection-error.deleted means the error was resolved. connection.schedule-stuck covers a resource's regular sync that has stopped progressing, while connection.sync-job-stuck covers a single sync job. connection.force-sync-completed follows a sync you triggered through the sync endpoint.

Setting up Trackstar webhooks

  1. Open the Webhooks page in the Trackstar dashboard and add an endpoint, for example https://example.com/webhooks/trackstar. It must accept POST with Content-Type: application/json.
  2. Choose event types. connection.created, connection.historical-sync-completed, connection-error.created, order.created and order.updated are a reasonable start.
  3. Narrow further if you need to: the Tags tab filters by connection ID or resource ID.
  4. Open the endpoint and copy its signing secret into TRACKSTAR_WEBHOOK_SECRET. Trackstar doesn't show the format, but Svix endpoint secrets start with whsec_; keep the prefix.

A new connection is quiet at first. Resource events are only sent for changes detected after the initial sync, and connection.historical-sync-completed arrives once per resource type when its initial sync ends. Read the backlog through the API at that point, or poll GET /connections/{connection_id} and check historical_sync_completed.

Trackstar has no separate test and production webhook environments. Its suggested answer is a transformation, set under the endpoint's Advanced tab, that changes webhook.url based on webhook.payload.connection_id or integration_name. One of Trackstar's examples reads webhook.payload.customer_id, a field the message schema doesn't list, so check a real payload before copying it.

Forward deliveries to a local server with the Hookdeck CLI:

npx hookdeck-cli listen 3000 trackstar --path /webhooks/trackstar

With Hookdeck. Add a Trackstar source's URL as an endpoint in the Webhooks portal and paste in that endpoint's signing secret. The source verifies the svix-* headers, accepts POST only and answers 200, and a request with a bad signature is logged as failed instead of being forwarded. Instead of a Svix transformation, you can split test and production traffic in Hookdeck with filters on connection_id, one connection per environment.

Securing Trackstar webhooks

From Svix's page: HMAC-SHA256 over {svix-id}.{svix-timestamp}.{raw body}, keyed with the base64-decoded part of the secret after whsec_, base64-encoded and compared with each v1, entry in svix-signature. The function below implements it and accepts webhook-* headers if the svix-* ones are missing:

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

function decodeBase64(value) {
  if (typeof value !== 'string' || !/^[A-Za-z0-9+/]+={0,2}$/.test(value)) return null;
  const bytes = Buffer.from(value, 'base64');
  return bytes.length > 0 && bytes.toString('base64').replace(/=+$/, '') === value.replace(/=+$/, '')
    ? bytes : null;
}

function verifySignature(rawBody, headers, secret) {
  if (!Buffer.isBuffer(rawBody) || typeof secret !== 'string' || !secret) return false;
  const prefix = headers['svix-id'] ? 'svix' : 'webhook';
  const id = headers[`${prefix}-id`];
  const timestamp = headers[`${prefix}-timestamp`];
  const signature = headers[`${prefix}-signature`];
  if (typeof id !== 'string' || !id || typeof timestamp !== 'string' ||
      !/^[0-9]+$/.test(timestamp) || typeof signature !== 'string') return false;
  const key = decodeBase64(secret.replace(/^whsec_/, ''));
  if (!key) return false;
  const message = Buffer.concat([Buffer.from(`${id}.${timestamp}.`, 'utf8'), rawBody]);
  const candidates = signature.split(/\s+/).filter((item) => item.startsWith('v1,')).map((item) => item.slice(3));
  const expected = crypto.createHmac('sha256', key).update(message).digest();
  return candidates.some((candidate) => {
    const received = decodeBase64(candidate);
    if (!received) return false;
    return received.length === expected.length && crypto.timingSafeEqual(received, expected);
  });
}

If a transformation edits the payload, the signature covers the edited body, so always verify the bytes you receive. A handler that uses previous_attributes:

const express = require('express');

// Returns the parsed body when it is a JSON object, otherwise null.
function parseJsonObject(rawBody) {
  try {
    const value = JSON.parse(rawBody.toString('utf8'));
    return value && typeof value === 'object' && !Array.isArray(value) ? value : null;
  } catch {
    return null;
  }
}

const app = express();

app.post('/webhooks/trackstar', express.raw({ type: '*/*' }), async (req, res) => {
  const secret = process.env.TRACKSTAR_WEBHOOK_SECRET;
  if (!secret) return res.sendStatus(500);
  if (!verifySignature(req.body, req.headers, secret)) return res.sendStatus(401);

  const payload = parseJsonObject(req.body);
  if (!payload) return res.sendStatus(400); // signed, but not a JSON object
  const { event_type, connection_id, data, previous_attributes } = payload;
  if (typeof event_type !== 'string' || !data || typeof data !== 'object') return res.sendStatus(400);

  const message_id = req.headers['svix-id'] || req.headers['webhook-id'];
  try {
    if (await inbox.has(message_id)) return res.sendStatus(200);

    switch (event_type) {
      case 'connection.historical-sync-completed':
        await backfill.schedule(connection_id, data);
        break;
      case 'order.updated':
        if (previous_attributes && 'status' in previous_attributes) {
          await orders.statusChanged(connection_id, data.id, previous_attributes.status, data.status);
        }
        break;
      case 'connection-error.created':
        await customers.notifyConnectionError(connection_id, data);
        break;
      default:
        break;
    }
    await inbox.add(message_id);
  } catch {
    return res.sendStatus(503); // not processed, so don't acknowledge
  }
  return res.sendStatus(200);
});

inbox, backfill, orders and customers stand for your own code.

Svix's libraries reject a timestamp older than five minutes. Hookdeck has no tolerance and keeps the original svix-timestamp when it retries or replays a delivery, so don't put an unmodified library check behind it. The function above checks the signature only.

Make Trackstar webhooks production-ready. Hookdeck Event Gateway evens out the bursts that follow a sync and routes order, inventory and connection events to the services that own them.

Trackstar webhook limitations and pain points

Event names are inconsistent

The Problem: A handler written against one spelling misses events sent with another.

Why It Happens: Most resources use hyphens, inventory_ledger.* uses an underscore, and Trackstar's sample writes inbound_shipment.updated where the event page says inbound-shipment.updated. Which form is on the wire hasn't been confirmed.

Workarounds:

  • Normalise - and _ before matching, or match both spellings.
  • Log unknown event names instead of dropping them silently.

How Hookdeck Can Help: Hookdeck's request log shows the exact event_type of every delivery, so you can confirm the spelling from real traffic.

Events lag the source system

The Problem: A change in the WMS takes a while to reach your endpoint, and nothing arrives during a connection's initial sync.

Why It Happens: Resource events come from Trackstar's sync schedule, not from the WMS directly.

Workarounds:

  • Read the initial data through the API after connection.historical-sync-completed.
  • Use a force sync through the API when you need fresh data sooner, and listen for connection.force-sync-completed.

How Hookdeck Can Help: Hookdeck can't speed up Trackstar's syncs, but it queues each sync's burst of events and delivers them at a rate your service can take.

Retries and ordering are undocumented

The Problem: You don't know how long Trackstar retries, how long it waits for a response, or whether events arrive in order.

Why It Happens: Trackstar's docs make no statement on any of the three. Svix's defaults may apply, but Trackstar doesn't confirm that.

Workarounds:

  • Acknowledge fast with a 2xx and process from a queue.
  • Compare data.updated_date (where the resource has one) before overwriting a record.

How Hookdeck Can Help: Hookdeck acknowledges Trackstar at once and handles retries to your service on a schedule you choose.

No payload schemas

The Problem: You can't validate payloads against a published schema.

Why It Happens: The per-event pages carry empty schemas, and the one sample message isn't valid JSON.

Workarounds:

  • Capture real deliveries for the events you use and build your types from them.

How Hookdeck Can Help: Every request is stored in full in Hookdeck, so real payloads are easy to inspect and copy.

Best practices

Wait for the historical sync

Treat connection.historical-sync-completed as the start signal for each resource type on a new connection, and backfill from the API.

Use previous_attributes

Act on the fields that changed. An order.updated without status in previous_attributes probably doesn't need a customer notification.

Deduplicate on the message ID

Store svix-id with the effect it produced, so a retry doesn't repeat it; the webhook idempotency guide has patterns for that.

Watch connection health

connection-error.created, connection.sync-job-stuck and connection.schedule-stuck mean data has stopped flowing. Alert on them as well as on missing webhooks.

Conclusion

Trackstar's webhooks cover everything from connection health to individual order lines, and previous_attributes makes updates easy to act on. Plan around the sync-driven timing, the quiet initial sync, the inconsistent event names and the missing retry details.

Hookdeck Event Gateway queues and routes Trackstar's events and retries your services when they fail. Sign up and add a Trackstar source as an endpoint in the Webhooks portal.


Gareth Wilson

Gareth Wilson

Product Marketing

Multi-time founding marketer, Gareth is PMM at Hookdeck and author of the newsletter, Community Inc.