WMS webhook — Trackely Docs

Send orders from your WMS, e‑commerce, or TMS into Trackely in real time. Your system POSTs order data to a tenant-specific URL; Trackely creates or updates orders and optionally geocodes addresses.

Getting the URL and secret

In the dashboard, go to Settings → Integrations (admin only). Click "Connect WMS" to create a webhook. You will see:

Webhook URL — {origin}/api/integrations/wms/{tenantId}
Secret — shown once; use it as a Bearer token. Store it securely (e.g. in your WMS integration settings). You can regenerate a new secret later from the same page.

Authentication

Every request must include the secret in the Authorization header:

Authorization: Bearer YOUR_SECRET

If the secret is wrong or missing, the API returns 401 Unauthorized.

Payload

Send a JSON body: either a single order object or an array of order objects. Each order is created or updated by externalOrderId (idempotent per tenant).

Field	Required	Description
externalOrderId	Yes	Your order reference. Same ID = update existing order.
deliveryAddress	If no customerId	Full delivery address. Used to create or find a customer and to geocode.
customerId	If no deliveryAddress	Existing Trackely customer ID.
customerName	No	Used when creating a customer from deliveryAddress (default "WMS Customer").
customerContact	No	Contact when creating customer (default "N/A").
totalWeight	No	Order weight in kg.
volume	No	Volume in m³.
palletCount	No	Number of pallets.
specialHandling	No	Array of strings (e.g. ["fragile", "timed_slot"]).
plannedDate	No	Delivery date in ISO format (YYYY-MM-DD). Orders appear in Planning for this date.

Example (single order)

{
  "externalOrderId": "WMS-ORD-001",
  "deliveryAddress": "10 High Street, London SW1A 1AA",
  "customerName": "Acme Ltd",
  "customerContact": "deliveries@acme.com",
  "totalWeight": 25.5,
  "palletCount": 1,
  "plannedDate": "2025-02-22"
}

Example (batch)

[
  {
    "externalOrderId": "WMS-ORD-001",
    "deliveryAddress": "10 High Street, London SW1A 1AA",
    "customerName": "Acme Ltd",
    "totalWeight": 25.5
  },
  {
    "externalOrderId": "WMS-ORD-002",
    "customerId": "clxx...",
    "totalWeight": 10,
    "plannedDate": "2025-02-22"
  }
]

cURL example

curl -X POST "https://trackely.co.uk/api/integrations/wms/YOUR_TENANT_ID" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_SECRET" \
  -d '{"externalOrderId":"ORD-1","deliveryAddress":"10 High St, London SW1A 1AA","customerName":"Acme","plannedDate":"2025-02-22"}'

Batch behaviour

You can send a single order object or an array of order objects. Processing is fail-fast: if any item fails validation (e.g. missing required field, invalid customerId, or invalid plannedDate), the API returns an error immediately and does not create or update any orders. Fix the payload and retry. externalOrderId is used for idempotency: the same ID in a later request updates the existing order.

Pull from WMS

Instead of your WMS pushing to Trackely, you can have Trackely pull orders from a URL. In Settings → Integrations, use the "Pull from WMS" section: add a pull endpoint with your WMS URL and method (GET or POST). Trackely will call that URL with Authorization: Bearer <secret>. Your endpoint must return the same JSON shape as the webhook (single order object or array of order objects). Use "Sync now" to pull on demand; optional scheduled sync may be added in the future. The secret is generated when you add the endpoint and shown once — store it in your WMS so it can verify the request.

Response and errors

Success (200): { "accepted": true, "processed": N, "orders": [ { "externalOrderId", "orderId", "created" }, ... ] }. lastReceivedAt for the webhook config is updated only after successful processing.

401 Unauthorized: Wrong or missing Bearer secret, or the webhook config is inactive (e.g. deactivated in Settings → Integrations). lastReceivedAt is not updated.

400 Bad Request: Invalid JSON or payload shape; or a validation error (e.g. customer not found, or neither customerId nor deliveryAddress provided). Response includes error and optional details.

422 Unprocessable Entity: Invalid plannedDate (e.g. not YYYY-MM-DD or not a valid calendar date). Response includes error and fieldErrors.plannedDate with per-item messages.

For other ways to get orders into Trackely, see Importing orders.