Agent skill
Trackstar Webhooks Skill
Receive and verify Trackstar webhooks (unified API for WMS, cart, carrier and freight systems, delivered via Svix). Use when setting up Trackstar webhook handlers, debugging svix-signature verification, or handling events like order.created, order.updated, inventory.updated, and connection.historical-sync-completed.
Install this skill
npx skills add hookdeck/webhook-skills --skill 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.updatedorinventory.updatedevents? - 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).
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
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/, examples/nextjs/, 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, 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, which has the full list and payload shape.
Environment Variables
# Signing secret of the webhook endpoint (Svix format, expected to start with whsec_)
TRACKSTAR_WEBHOOK_SECRET=whsec_xxxxx
Local Development
# 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 of the Trackstar dashboard, then trigger an event (for example, connect a sandbox integration) to see it arrive.
Reference Materials
- references/overview.md - Trackstar webhook concepts, all 47 events, payload shape
- references/setup.md - Register an endpoint, get the secret, transformations, initial-sync behavior
- references/verification.md - Svix verification details, header fallback, manual verifier, timestamp window