TMS Integration Starter Template: Tendering, Dispatching, and Tracking with Webhooks

Stop reinventing TMS flows — quick, safe starter kit for tendering, dispatching, and tracking with webhooks

If you build integrations for TMS platforms or provide carrier-facing APIs, you know the pain: implementing tendering, dispatch, and tracking flows is boring, error-prone, and brittle across carriers. You also need sample webhooks, a predictable simulator for truck state transitions, and a tiny UI to validate end-to-end dispatch flows. This starter template boilerplate solves that exact problem: production-ready endpoints, a webhook emulator, simulated truck state machine, and a lightweight UI so teams can iterate fast without disrupting real fleets.

Why this boilerplate matters in 2026

Logistics integrations matured fast between 2023–2025: major TMS vendors started shipping API-first features and in late 2025 early 2026 we saw the first autonomous truck TMS links go live. The Aurora–McLeod announcement (autonomous truck capacity inside a TMS) signaled that tendering and dispatch systems must be async, event-driven, and secure. Today, TMS integrations must support:

• Asynchronous tendering and acceptance flows (tenders, offers, auto-acceptance).
• Reliable webhooks for state changes and exception handling.
• Observable simulations so QA and product teams can replay every truck state.
• Security and compliance (OAuth 2.0, mTLS, signatures, audit trails).

The starter kit below implements these patterns in a small, extensible repo so vendors and integrators can focus on business logic instead of plumbing.

What you get in this TMS starter kit

The repo is intentionally minimal but complete:

• /api — Tendering, dispatching, and tracking REST endpoints (Express.js example).
• /simulator — Truck state machine and webhook dispatcher for end-to-end tests.
• /webhooks — Example webhook payloads and verification helper code.
• /ui — Small React app to visualize dispatch flows and replay simulations.
• docker-compose.yml — Start services (API, simulator, UI, Redis) locally.
• tests/ — Integration tests that validate tender->dispatch->tracking workflows.
• README — Setup, security guidance, and extension points.

Architecture at a glance

The starter template follows an event-driven, API-first architecture:

1. Client (TMS or broker) POSTs a tender to /api/tenders.
2. API enqueues the tender and responds with 202 Accepted + tender id.
3. Operator or automated rules accept or reject a tender (web UI, API).
4. When accepted, an internal job creates a dispatch and assigns a simulated truck.
5. The simulator advances truck states (dispatched -> enroute -> delivered) and emits webhooks to the integrator endpoint.
6. All events are stored in Redis/Postgres; the UI subscribes to a websocket for live visualization.

Why event-driven?

Event-driven models decouple sending a tender from the long-running lifecycle of a freight move. It makes the system resilient to downstream outages (webhook consumer down) and aligns with modern TMS expectations for asynchronous capacity APIs — the same patterns that enabled autonomous truck integrations in 2025–2026.

Key endpoints (examples)

Below are the core endpoints you’ll find in the boilerplate. They intentionally match common TMS patterns so your team can drop them into real integrations.

Tendering endpoints

• POST /api/tenders — Create a tender. Returns { tenderId, status: 'pending' }.
• GET /api/tenders/:id — Retrieve tender status and assignments.
• POST /api/tenders/:id/response — Accept or reject a tender (carrier).

Dispatching & tracking

• POST /api/dispatches — Create a dispatch manually or automatically when a tender is accepted.
• GET /api/dispatches/:id — Fetch dispatch details and last-known state.
• POST /api/dispatches/:id/commands — Manual commands: start, pause, reroute.

Webhook endpoints (for testing)

• POST /api/webhooks/subscribe — Register where simulated events should be delivered.
• POST /api/webhooks/test — Send a sample webhook to a registered callback (useful for partner onboarding).

Sample webhook payloads

Webhooks are JSON with a consistent envelope containing metadata, event type, and a compact payload. Always sign payloads (HMAC) in production — the template includes a X-Signature header verifier.

{
  "event_id": "evt_01FZ9Y12345",
  "event_type": "dispatch.state_changed",
  "occurred_at": "2026-01-12T14:05:03Z",
  "source": "tms-boilerplate",
  "data": {
    "dispatch_id": "dsp_1234",
    "tender_id": "tnd_5678",
    "vehicle_id": "truck_42",
    "state": "enroute",
    "location": { "lat": 41.8781, "lon": -87.6298 },
    "eta_minutes": 72
  }
}

Actionable tip: include a stable event_id and event_type so consumers can deduplicate and easily route events. The repo includes a verification function for the signature header and retries with exponential backoff.

Simulated truck state machine

The simulator is the heart of the starter kit — it advances virtual trucks through deterministic states. Use it to write integration tests and to validate partner webhooks before hitting production fleets.

States

• idle — Truck available.
• assigned — Truck has an assigned dispatch but not yet departed.
• dispatched — Truck is en route to pickup.
• pickup_complete — Loaded and heading to delivery.
• enroute — In transit to destination.
• delivered — Delivery completed.
• exception — Incidents (breakdown, re-route, ETA delay).

Simple transition function (Node.js pseudocode)

const State = ['idle','assigned','dispatched','pickup_complete','enroute','delivered','exception']

function advance(truck) {
  switch (truck.state) {
    case 'idle': truck.state = 'assigned'; break;
    case 'assigned': truck.state = 'dispatched'; break;
    case 'dispatched': truck.state = 'pickup_complete'; break;
    case 'pickup_complete': truck.state = 'enroute'; break;
    case 'enroute': truck.state = 'delivered'; break;
    default: break;
  }
  truck.eta_minutes = Math.max(0, truck.eta_minutes - randomStep())
  emitWebhook('dispatch.state_changed', truck)
}

The real repo exposes knobs: speed multiplier, failure injection (to simulate exceptions), and per-dispatch timeline overrides. Use these to test retry logic in your webhook consumers.

UI: visualize dispatch flows

The included React UI is intentionally tiny (~500 LOC) and demonstrates how to render live dispatch states. It connects to the API over a websocket for low-latency updates and offers the following features:

• List of recent tenders and their status.
• Live map view of simulated trucks with color-coded states.
• Replay control: step, play, fast-forward (speed multiplier).
• Webhook inspector: view events sent to registered callbacks and their signature verification.

Actionable integration tip: run the UI in a separate tab while onboarding a carrier partner; it’s extremely useful to watch webhook sequences in real time.

Security checklist (must-haves)

The starter kit implements secure defaults, but you should verify everything before production:

• Authentication: OAuth 2.0 client credentials for API-to-API calls.
• Webhook signing: HMAC-SHA256 signatures (X-Signature) and replay protection using timestamps.
• Transport security: mTLS for partner connections when required.
• Rate limiting: per-client and per-IP throttles for tender endpoints.
• Audit logs: immutable capture of tenders, responses, and webhook deliveries (persist to write-once store or append-only table).
• Data minimization: avoid storing PII unless necessary; use tokenized references.

Testing and partner onboarding

Onboarding partners for 2026 TMS integrations favors automated checks. The repo ships with a small test harness:

• Webhook replay tests that assert idempotency.
• Contract tests using JSON Schema for each API and webhook payload.
• Simulated failure scenarios (lost delivery, late ETA) to validate exception handling.

Practical guide: use ngrok or a similar tunnel during partner onboarding to expose a local webhook receiver. Provide partners with a test API key and the following checklist:

1. Subscribe webhook to /api/webhooks/subscribe with a test callback URL.
2. Send a tender and wait for dispatch lifecycle events.
3. Verify X-Signature and timestamp freshness on incoming webhooks.
4. Run the JSON Schema validator against the webhook payloads.

Deployment & CI/CD

Ship the template with a simple Docker Compose for local dev and a production-ready path using GitHub Actions + Terraform or Kubernetes manifests. Key deployment notes:

• Run simulator in a separate process so you can scale it independently from the API.
• Store state in Postgres for authoritative records and Redis for ephemeral job queues.
• Expose metrics (Prometheus) for tender acceptance rate, webhook success ratio, and average processing latency.
• Use feature flags to enable/disable simulated autonomous-capacity routing (e.g., Aurora-like integration).

Observability: what to measure

Monitoring matters. The repo includes sample Grafana dashboards measuring:

• Webhook delivery latency and success rate (per-client).
• Tender throughput (per hour/day).
• Average time from tender submission to accepted dispatch.
• Simulator health: average processing time for state transitions and queue length.

Advanced strategies for 2026 and beyond

As the industry embraces autonomous trucking and edge-connected vehicles, integrations will need to adapt. Here are practical strategies you can apply to this starter kit:

• Hybrid edge-cloud model: let trucks publish telemetry to an edge broker and relay canonical state to your TMS via the webhook bridge in the starter kit.
• Event mesh: use Kafka or NATS to stream dispatch events across microservices and partners for lower latency and replayability.
• Capacity-as-a-service: expose an offer API allowing carriers (including autonomous providers) to bid on tenders programmatically.
• Policy-driven routing: integrate policy engines (OPA) to enforce constraints (hazmat, lane restrictions) during automatic acceptance.

Case study: why a TMS vendor used this pattern

In early 2026, several TMS vendors prioritized API-first tendering to support new autonomous capacity providers. One McLeod customer reported faster tender-to-dispatch times when they adopted an async tendering flow and webhook-based tracking: manual handling dropped, and exceptions were caught earlier through simulated tests. The starter kit mirrors those production lessons — decoupled lifecycles, signature-verified webhooks, and a simulator for safe partner onboarding.

Repo structure and quick-start (practical)

Clone and run the template locally in minutes:

git clone https://github.com/yourorg/tms-starter-template.git
cd tms-starter-template
# Start local services
docker-compose up --build

# Open UI
# http://localhost:3000
# API docs
# http://localhost:4000/docs

Essential env variables:

• API_PORT=4000
• SIMULATOR_SPEED=1 (1x realtime)
• WEBHOOK_SECRET=replace_with_secret
• REDIS_URL, DATABASE_URL

Extending the boilerplate

The template is intentionally opinionated but extensible. Here are immediate extension points to support production use cases:

1. Add provider adapters: implement a driver interface for each carrier (REST, EDI, proprietary).
2. Policy plugin: attach a rules engine to auto-accept or reject tenders based on SCAC, equipment, and lanes.
3. Carrier portal: a dedicated UI for carriers to accept tenders and view analytics.
4
4. Audit exports: scheduled reports for compliance and billing.

Licensing and contribution guidance

The repo uses a permissive license (MIT recommended) so teams can fork and adapt to proprietary needs. If you publish a fork, mark any production changes clearly and add a security disclosure document describing how to rotate webhook secrets and revoke keys.

Common pitfalls and how to avoid them

• Ignoring idempotency: Always include event_id and implement dedupe in webhook consumers.
• Overloading synchronous APIs: Tender endpoints should return quickly and move processing to a queue.
• Poor signature handling: Validate timestamps and use constant-time signature comparisons to prevent replay or timing attacks.
• Skipping simulations: Tests that don’t simulate failures will miss real-world edge cases.

Actionable checklist — 10-minute integration plan

1. Clone repo and run docker-compose.
2. Register a test webhook callback (ngrok) and subscribe via /api/webhooks/subscribe.
3. POST a tender to /api/tenders and watch the UI map for assigned truck.
4. Confirm receipt of at least the following webhook events: tender.created, tender.response, dispatch.state_changed.
5. Run the JSON Schema tests in tests/ to validate payload shape.
6. Enable signature verification using WEBHOOK_SECRET and verify on your side.

Final thoughts: use this as a foundation, not a product

This starter template is a robust scaffolding for modern TMS integrations in 2026. It codifies best practices — async tendering, webhook-first tracking, simulated fleets, and a minimal UI — so teams can avoid reinventing the plumbing. It’s not a drop-in production system, but it is the safest, fastest path to a working integration that can evolve into a hardened service.

“The future of freight is event-first and API-native. Build the plumbing once; iterate on business rules forever.”

Call to action

Ready to accelerate partner integrations? Clone the starter template, run the simulator, and invite a partner to a private test environment today. If you want a trimmed-down version for embedded demos or a hardened production checklist for enterprise TMS, open an issue in the repo — we’ll add examples for autonomous-capacity adapters (Aurora-style) and carrier-specific adapters.

Get started now: git clone https://github.com/yourorg/tms-starter-template and follow the README to spin up a working tender -> dispatch -> tracking demo in under 10 minutes.

Related Reading

• Staging Science: Using Theatre and Opera to Teach Environmental Topics
• Traffic Growth from Audits: Real Fix Prioritization Framework for Small Teams
• Art Auctions for Bargain Hunters: How a Postcard-Sized Renaissance Drawing Reached $3.5M and What to Learn
• Leadership Moves: What Liberty’s New Retail MD Appointment Means for Luxury Accessory Buyers
• Heat and Hydration: How Hot‑Water Bottles Can Help (and Hurt) Your Skin After Treatments