# Guide to Trackstar Webhooks: Features and Best Practices

[Trackstar](https://trackstarhq.com) 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](https://dashboard.trackstarhq.com/webhooks) is a Svix portal, where you add endpoints, filter which messages they receive and attach JavaScript transformations. For signatures, Trackstar's [webhooks guide](https://docs.trackstarhq.com/how-to-guides/webhooks/webhooks) 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:

```json
{
  "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

1. Open the [Webhooks page](https://dashboard.trackstarhq.com/webhooks) 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](/docs/cli):

```bash
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](/docs/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:

```javascript
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`:

```javascript
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](/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](/docs/destinations) 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](/docs/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](/webhooks/guides/implement-webhook-idempotency) 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](https://hookdeck.com) queues and routes Trackstar's events and retries your services when they fail. [Sign up](https://dashboard.hookdeck.com/signup) and add a Trackstar source as an endpoint in the Webhooks portal.