# Trackstar Webhooks

Trackstar uses Svix as its webhook provider, which implements
Standard Webhooks. Every delivery is an HTTP `POST` with a JSON body and three signature
headers: `svix-id`, `svix-timestamp`, and `svix-signature`. The event name is the top-level
`event_type` field. The body also carries `connection_id`, `integration_name`, `data` (the
created or updated object) and, on `*.updated` events only, `previous_attributes`.

## When to Use This Skill

* How do I receive Trackstar webhooks?
* How do I verify Trackstar webhook signatures (`svix-signature`)?
* How do I handle `order.created`, `order.updated` or `inventory.updated` events?
* How do I know when a connection's initial sync is done (`connection.historical-sync-completed`)?
* Why is my Trackstar webhook signature verification failing, or rejecting Hookdeck retries?

## Verification (core)

Signed content is `{svix-id}.{svix-timestamp}.{raw body}`. Svix signs it with HMAC-SHA256 using
the base64-decoded secret (the part after `whsec_`), base64-encodes the result, and sends one or
more space-separated `v1,<signature>` entries. Use the official `svix` library, which compares in
constant time. Read the `svix-*` headers, and when `svix-id` is absent fall back to the `webhook-*`
headers (`webhook-id`, `webhook-timestamp`, `webhook-signature`).

```javascript
import { Webhook } from 'svix'; // svix 2.x is ESM-only

const prefix = req.headers['svix-id'] ? 'svix' : 'webhook';
const id = req.headers[`${prefix}-id`];
const timestamp = req.headers[`${prefix}-timestamp`];
const signature = req.headers[`${prefix}-signature`];
// rawBody: the raw Buffer/string, never re-serialized JSON
new Webhook(process.env.TRACKSTAR_WEBHOOK_SECRET).verify(rawBody, {
  'svix-id': id, 'svix-timestamp': timestamp, 'svix-signature': signature,
  'webhook-id': id, 'webhook-timestamp': timestamp, 'webhook-signature': signature,
}); // throws on a bad signature or a timestamp outside the window
const event = JSON.parse(rawBody.toString('utf8')); // parse only after verify passes

```

```python
from svix.webhooks import Webhook, WebhookVerificationError

wh = Webhook(os.environ["TRACKSTAR_WEBHOOK_SECRET"])  # "whsec_..."
wh.verify(raw_body, {"svix-id": id, "svix-timestamp": ts, "svix-signature": sig,
                     "webhook-id": id, "webhook-timestamp": ts, "webhook-signature": sig})

```

> **For complete handlers with tests**, see [examples/express/](https://github.com/hookdeck/webhook-skills/tree/main/skills/trackstar-webhooks/examples/express/), [examples/nextjs/](https://github.com/hookdeck/webhook-skills/tree/main/skills/trackstar-webhooks/examples/nextjs/), [examples/fastapi/](https://github.com/hookdeck/webhook-skills/tree/main/skills/trackstar-webhooks/examples/fastapi/).

The secret is on the endpoint's page in the Trackstar dashboard's webhook portal (a Svix portal).
Each endpoint has its own. Trackstar's docs don't print the format, but Svix secrets start with
`whsec_`, so keep the full `whsec_...` value in `TRACKSTAR_WEBHOOK_SECRET`. Handlers fail closed: with
the variable unset they return 500 instead of accepting anything.

### Hookdeck retries and replays hit the 5-minute window

The `svix` and `standardwebhooks` libraries always enforce a fixed 5-minute timestamp window, and
it can't be configured. Hookdeck retries and replays resend the **original** `svix-timestamp`, so
the library rejects any retry or replay that happens more than 5 minutes after the original
delivery. If you verify behind Hookdeck (or replay old events), use the manual verifier in
[references/verification.md](https://github.com/hookdeck/webhook-skills/blob/main/skills/trackstar-webhooks/references/verification.md), where the window can be dropped or
widened. Deduplicate on `svix-id` instead of relying on the timestamp.

## Common Event Types

47 events are documented (the list may not be exhaustive). The name is `event_type` in the JSON
body. The examples handle these:

| Event | Triggered When |
| --- | --- |
| `connection.created` | A customer connects an integration |
| `connection.deleted` | A connection is deleted |
| `connection.historical-sync-completed` | The initial sync finishes for a resource type (resource events aren't sent before this) |
| `connection.sync-job-stuck` | Trackstar decides a sync job won't progress |
| `connection-error.created` | A connection error is raised |
| `install.failed` | An integration install fails before a connection is created |
| `order.created` | An order is created in the WMS |
| `order.updated` | An order changes; `previous_attributes` holds the old values |
| `order.shipment.created` | A shipment is created for an order |
| `inventory.updated` | An inventory item changes |
| `inbound-shipment.updated` | An inbound shipment changes |

Names are not fully consistent: most use hyphens (`inbound-shipment.updated`) but
`inventory_ledger.created` uses an underscore. Copy them from
[references/overview.md](https://github.com/hookdeck/webhook-skills/blob/main/skills/trackstar-webhooks/references/overview.md), which has the full list and payload shape.

## Environment Variables

```bash
# Signing secret of the webhook endpoint (Svix format, expected to start with whsec_)
TRACKSTAR_WEBHOOK_SECRET=whsec_xxxxx

```

## Local Development

```bash
# Start tunnel (no account needed)
npx hookdeck-cli listen 3000 trackstar --path /webhooks/trackstar

```

Register the tunnel URL as an endpoint on the [Webhooks page](https://dashboard.trackstarhq.com/webhooks)
of the Trackstar dashboard, then trigger an event (for example, connect a sandbox integration)
to see it arrive.

## Reference Materials

* [references/overview.md](https://github.com/hookdeck/webhook-skills/blob/main/skills/trackstar-webhooks/references/overview.md) - Trackstar webhook concepts, all 47 events, payload shape
* [references/setup.md](https://github.com/hookdeck/webhook-skills/blob/main/skills/trackstar-webhooks/references/setup.md) - Register an endpoint, get the secret, transformations, initial-sync behavior
* [references/verification.md](https://github.com/hookdeck/webhook-skills/blob/main/skills/trackstar-webhooks/references/verification.md) - Svix verification details, header fallback, manual verifier, timestamp window