Guide to Trackstar Webhooks: Features and Best Practices
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.
| Aspect | Value |
|---|---|
| Method | POST, Content-Type: application/json |
| Signature headers | svix-id, svix-timestamp, svix-signature (Standard Webhooks; webhook-* carry the same values) |
| Event name | Top-level event_type |
| Timing | Resource 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
| Feature | Details |
|---|---|
| Signature | Standard Webhooks HMAC-SHA256 |
| Signature header | svix-signature |
| Body | JSON |
| Event routing | Body field event_type |
| Delivery platform | Svix |
| Configuration | Dashboard Webhooks page (Svix portal) |
| Filters | Event type, connection ID, resource ID, date |
| Transformations | JavaScript, per endpoint |
| Change tracking | previous_attributes on updates |
| Secret format | Not printed (Svix issues whsec_) |
| Retries, timeout, ordering | Not documented |
Events and payloads
| Field | Description |
|---|---|
event_type | The event name, e.g. order.updated |
connection_id | The connection the event came from |
integration_name | The integration (e.g. a WMS) the event came from |
data | The created or updated object |
previous_attributes | Only 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
| Event | Triggered When | Common Use Cases |
|---|---|---|
connection.created | A customer connects an integration | Start tracking the connection |
connection.deleted | A connection is deleted | Clean up stored credentials and data |
connection.historical-sync-completed | The initial sync finishes for a resource type | Start reading data (it is now queryable) |
connection.sync-job-stuck | Trackstar decides a sync job won't progress | Alert support |
connection-error.created | A connection error is raised | Prompt the customer to reconnect |
install.failed | An attempt to connect an integration fails before a connection exists | Show an install error |
order.created | An order is created in the WMS | Ingest the order |
order.updated | An order changes (previous_attributes has the old values) | Update status |
order.shipment.created | A shipment is created for an order | Send tracking |
inventory.updated | An inventory item changes | Sync stock levels |
inbound-shipment.updated | An inbound shipment changes | Track 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
- Open the Webhooks page in the Trackstar dashboard and add an endpoint, for example
https://example.com/webhooks/trackstar. It must acceptPOSTwithContent-Type: application/json. - Choose event types.
connection.created,connection.historical-sync-completed,connection-error.created,order.createdandorder.updatedare a reasonable start. - Narrow further if you need to: the Tags tab filters by connection ID or resource ID.
- Open the endpoint and copy its signing secret into
TRACKSTAR_WEBHOOK_SECRET. Trackstar doesn't show the format, but Svix endpoint secrets start withwhsec_; 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_ and check historical_.
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_ or integration_name. One of Trackstar's examples reads webhook.payload.customer_, 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
2xxand 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.