Webhook Integration Guide

Table of Contents

• Overview
• Webhook Events
• Source Setting Parameters
• Payload Schemas
• Authentication
• Error Handling & Logging

---

Overview

The TAI TMS webhook system allows your application to receive HTTP POST notifications when key events occur inside the platform — shipment lifecycle changes, customer and carrier record updates, and accounting document creation.

How It Works

Webhooks are configured through Source Settings in the TMS admin interface. Each webhook integration is an IntegrationSource of type PublicAPIWebhooks, scoped to one or more Linked Organizations. When a triggering event occurs for a record that belongs to a linked organization, the TMS serializes the relevant data and POSTs it as JSON to the URL(s) you have configured.

TMS Event Occurs
      │
      ▼
Linked Organization matches?
      │ Yes
      ▼
(For shipment events) Batch in ~1-min window
      │
      ▼
Serialize payload (camelCase JSON)
      │
      ▼
POST to configured URL
      │
      ▼
Log result to WebhookActivityLog

Key Behaviors

Shipment Webhook Batching

Shipment-related webhooks (ShipmentCreateUrl, ShipmentDetailUpdateUrl, ShipmentStatusUpdateUrl, ShipmentLocationUpdateUrl, ShipmentLocationUpdateExtendedUrl) are dispatched via a background queue with a ~1-minute delay after the triggering event. Multiple edits to the same shipment within that window coalesce into a single delivery — the timer resets on each new change and fires ~1 minute after the last change is saved. This prevents duplicate webhooks when users make multiple edits in quick succession.

Accounting, customer, and carrier webhooks are dispatched immediately, with one exception: BillCreateUrl uses a background job with a ~5-second delay.

Versioning

The Version source setting controls the shape of shipment payloads and how statuses are represented. It applies only to shipment webhooks (Create, Detail, Status, Location, LocationExtended). Accounting, customer, and carrier payloads are unversioned and always use the current schema.

Only the string values "1" and "2" are explicitly recognized. If Version is missing, empty, or set to any other value (including "3"), the payload is sent in V3 form.

---

Webhook Events

Each URL parameter in your Source Setting corresponds to a distinct event type. Multiple URL parameters can be configured on a single Source Setting; each fires independently.

Shipment Events

ShipmentCreateUrl

Fires when a new shipment is created in the TMS.

• Trigger: A new shipment is persisted for the first time via the BackOffice UI, Public API POST, EDI 204 inbound, or system-generated flow.
• Payload: Full shipment details (ShipmentDetails).
• Delivery: Batched with a ~1-minute delay (see Shipment Webhook Batching above).
• Notes: If ShipmentCreateUrl is not configured but ShipmentDetailUpdateUrl is, the creation event delivers to ShipmentDetailUpdateUrl instead.

ShipmentDetailUpdateUrl

Fires when an existing shipment's details are modified.

• Trigger: Any update to shipment information — stops (address, contact, dates, add/remove/reorder), commodities, accessorials, carrier/transit-leg assignment, reference numbers, customer, quotes, and more.
• Payload: Full shipment details (ShipmentDetails), reflecting the state after the update.
• Delivery: Batched with a ~1-minute delay.
• Notes: ShipmentDetailUpdateUrl also fires alongside ShipmentStatusUpdateUrl on every status change. If you subscribe to both, expect paired deliveries on status transitions.

ShipmentStatusUpdateUrl

Fires on shipment status changes and on certain transit-related edits.

• Trigger: Any of the following:
  • Shipment status transitions (Quote, Committed, Dispatched, InTransit, OutForDelivery, Delivered, Complete, Canceled, Reinstated)
  • Stop date/time edits on any stop — FirstPick, LastDrop, or additional stops — including scheduled, appointment, and actual arrival/departure times
  • Stop add/delete on additional stops
  • Bulk stop-date updates
  • EDI 214 status updates (v1 and v2)
  • Public API Tracking Updates and Check Call events
• Payload: Full shipment details (ShipmentDetails) including the current status. Note that the payload's status may match the previous webhook's status when the trigger was a non-status change (e.g., a stop-date edit).
• Delivery: Batched with a ~1-minute delay. There is no additional throttle. Every triggering event within the queue window fires the webhook once.
• Notes: ShipmentDetailUpdateUrl fires alongside this webhook from the same handler if subscribed.

Status values by version:

ShipmentLocationUpdateUrl

Fires when a new GPS/location update is received for a shipment.

• Trigger: A location ping is recorded for the shipment via:
  • Public API POST /PublicApi/Location/v2/ShipmentLocations
  • Driver-tracking provider callbacks (MacroPoint, TruckerTools, FourKites, Project44, FarEye, OpenTrack)
• Payload: Simplified shipment data focused on location — shipment ID, status, latitude, longitude, location string, and last location update timestamp.
• Delivery: Batched with a ~1-minute delay.
• Throttle: Fires at most once every 15 minutes per shipment. Additional location pings within the 15-minute window are silently dropped from the webhook (the underlying location data is still stored).

ShipmentLocationUpdateExtendedUrl

Fires from the same triggers as ShipmentLocationUpdateUrl but delivers a richer payload including full shipment context.

• Trigger: Same as ShipmentLocationUpdateUrl.
• Payload: Extended shipment + location payload.
• Delivery: Batched with a ~1-minute delay.
• Throttle: 15-minute window, tracked separately from ShipmentLocationUpdateUrl. Each webhook has its own 15-minute counter, so subscribing to both is safe — one throttling the other has no effect.

Accounting Events

BillCreateUrl

Fires when a carrier/vendor bill is approved through the Approve Bill workflow.

• Trigger: A bill completes the approval workflow via POST /api/registerbills, bulk bill import, or a bill revision.
• Payload: Full bill details (Bill) including line items, payment status, and external sync details.
• Delivery: Background job with a ~5-second delay after the approval action. This is the only accounting webhook that is not synchronous.
• Subscription scoping: The bill's payerOrganizationId is matched against the Source Setting's Linked Organizations.

CommissionBillCreateUrl

Fires when a commission is approved to Created status via the Approve Commissions workflow.

• Trigger: Commission records transition to ChargeLineAccountingStatus.Created via PUT /api/approveCommissions (UI) or the Public API commission approval endpoint.
• Payload: Commission details (Commission), which mirrors the bill structure but represents agent/rep commissions.
• Delivery: Synchronous / immediate.
• Notes: Structurally identical to BillCreateUrl payloads but only fires on the "Created" transition — not on declines, variance moves, or other status changes.

InvoiceCreateUrl

Fires when a customer invoice is finalized.

• Trigger: The Invoice Create process completes for a customer invoice (create, revision/adjustment, consolidation, or manual regeneration via POST /api/invoices/generateDigitalInvoices).
• Payload: Invoice details only (Invoice) — organization info, line items, payment status, due dates, recipients.
• Delivery: Synchronous / immediate.
• Notes: See DoNotMarkInvoiceAsPrinted in Source Setting Parameters for behavior around the invoice's printed state after delivery.

InvoiceCreateWithShipmentUrl

Fires at the same moment as InvoiceCreateUrl but includes the associated shipment data.

• Trigger: Same as InvoiceCreateUrl.
• Payload: A composite object containing both invoice (Invoice) and shipmentDetails (ShipmentDetails).
• Delivery: Synchronous / immediate.
• Notes: If both InvoiceCreateUrl and InvoiceCreateWithShipmentUrl are configured on the same Source Setting, both fire with different payloads. Configure both only if your downstream system needs both shapes.

Customer Events

CustomerCreateUrl

Fires when a new customer organization is created.

• Trigger: A customer organization is persisted for the first time via Public API POST /PublicApi/Customer/v2/Customers or the BackOffice "New Customer" UI.
• Payload: Customer organization details (Organization).
• Delivery: Synchronous / immediate.
• Notes: Scoped to the parent organization hierarchy of the webhook's linked organization. Only customers whose ParentIds chain intersects the linked org will trigger this webhook.

CustomerUpdateUrl

Fires when an existing customer organization is modified — directly or indirectly.

• Trigger:
  • Any field update on a customer organization via Public API PUT or the BackOffice UI (name, address, phone, reference number, notes, etc.)
  • Indirect trigger: creating or updating the customer's Invoice Accounting Profile
  • Indirect trigger: Credit Limit changes on the customer
• Payload: Full updated customer details (Organization).
• Delivery: Synchronous / immediate.
• Notes: Same organization-hierarchy scoping as CustomerCreateUrl.

Carrier Events

LSPCarrierCreateUrl

Fires when a new carrier record is added via Highway integration onboarding.

• Trigger: The Highway onboarding webhook adds a new BrokerCarrier record.
• Payload: Carrier details (LSPCarrier) including carrier master info, insurance records, supported trailer types, contacts, payment preferences, and labels.
• Delivery: Synchronous / immediate.
• Notes: This webhook currently fires only on the Highway onboarding path. Carriers added via Public API POST /PublicApi/Carriers/v2/Carriers, the BackOffice "New Carrier" UI, or other integrations (DAT, DATConvoy, Truckstop, MyCarrier) do not trigger LSPCarrierCreateUrl.

LSPCarrierUpdateUrl

Fires when an existing carrier record is modified.

• Trigger: Any update to a broker carrier record via Public API PUT /PublicApi/Carriers/v2/Carriers, the BackOffice UI, or the Highway integration.
• Payload: Full updated carrier details (LSPCarrier).
• Delivery: Synchronous / immediate.
• Notes: Fires on any column change — status, terms, insurance, payment preferences, addresses, supported equipment, labels, etc.

---

Source Setting Parameters

When configuring a Source Setting of type PublicAPIWebhooks, the following parameters are available:

---

Payload Schemas

All payloads are delivered as a JSON object in the HTTP POST body. Property names are camelCase. Dates are ISO 8601 UTC strings (yyyy-MM-ddTHH:mm:ssK). Enum fields are serialized as strings, not integers.

Shipment Payloads

Used by: ShipmentCreateUrl · ShipmentDetailUpdateUrl · ShipmentStatusUpdateUrl

Version note: Version 1 uses the legacy ShipmentWebhookExport shape (see V1 Legacy Schema). Versions 2 and 3 use the schema below.

ShipmentDetails

CustomerDetailsV2

StaffDTO

PayerOrganization

ShippingAddress

Represents a single stop on the shipment route.

Commodity

CarrierDetails

Accessorial

ReferenceNumber

ShipmentAlert

StopCommodity

Links a commodity to a specific stop for pickup or delivery tracking.

Attachment

Location Payload

Used by: ShipmentLocationUpdateUrl

This is a trimmed-down view of the shipment focused purely on location data. It does not include full stop details, commodities, or financials.

LocationShipmentDetails

Bill Payload

Used by: BillCreateUrl

Bill

BillLineItem

BillPaymentLineItem

Commission Payload

Used by: CommissionBillCreateUrl

The commission payload mirrors the bill structure — the same field set representing agent or rep commissions rather than carrier/vendor bills. Uses the same nested types (Organization, Vendor, BillLineItem, BillPaymentLineItem, ExternalSyncDetails).

Invoice Payloads

Invoice

Used by: InvoiceCreateUrl · InvoiceCreateWithShipmentUrl (as invoice property)

InvoiceAccountingProfile

InvoiceLineItem

InvoicePaymentLineItem

InvoiceWithShipment

Used by: InvoiceCreateWithShipmentUrl

A composite wrapper — the root object has two properties:

Customer Payload

Used by: CustomerCreateUrl · CustomerUpdateUrl

Organization

This is also the shared type used within bill and invoice payloads wherever an organization reference appears.

Carrier Payload

Used by: LSPCarrierCreateUrl · LSPCarrierUpdateUrl

LSPCarrier

CarrierMasterInfo

CarrierContact

CarrierInsurance

SupportedTrailerType

CarrierParameter

Shared Object Types

These types appear across multiple payload schemas.

Address

ContactInformation

GeneralLedgerAccount

ExternalSyncDetails

Represents the sync state of a record to an external accounting system (e.g., QuickBooks Online).

Vendor

V1 Legacy: ShipmentWebhookExport

Used by: ShipmentCreateUrl · ShipmentDetailUpdateUrl · ShipmentStatusUpdateUrl when Version = 1

V1Address

V1Commodity

---

Authentication

All webhook communication is outbound — the TMS sends requests to your endpoint. You are responsible for securing your endpoint; the TMS provides the following mechanisms to prove the request is coming from the platform.

Transport Security

The TMS supports TLS 1.0, 1.1, and 1.2. TLS 1.3 is not currently supported. If your endpoint enforces TLS 1.3-only, webhook delivery will fail at the transport layer.

HTTPS is strongly recommended but not enforced. The TMS will POST to a plain http:// URL if configured — this exposes the Authorization header and payload in transit. There is no TLS pinning; standard OS certificate store validation applies.

Recommendation: Configure https:// endpoints only, and require TLS 1.2 on your endpoint.

Authentication Methods

Two authentication methods are available and are configured per Source Setting. They can be used independently or together — see the precedence note below.

Option 1 — Static Authorization Header

Set the Authorization source setting parameter to any string value. The TMS will include it verbatim as the Authorization header on every request. No prefix or transformation is added.

This is the most flexible option — it supports any scheme your endpoint requires:

# Bearer token
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

# Custom API key (if your endpoint expects this header)
Authorization: ApiKey abc123xyz

# HMAC signature (pre-computed and stored as a static value)
Authorization: HMAC sha256=abc123...

Source Setting parameter: Authorization

Option 2 — HTTP Basic Authentication

Set both the UserName and Password source setting parameters. The TMS will Base64-encode username:password and attach it as a standard Authorization: Basic header. Encoding uses ASCII.

Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ=

Special characters in usernames or passwords should be verified to survive ASCII encoding without truncation.

Source Setting parameters: UserName, Password

When Both Are Configured

If both Authorization and UserName/Password are set on the same Source Setting, Basic Authentication takes precedence. The effective header sent will be Authorization: Basic <base64(user:pass)>.

Verifying Requests Are From the TMS

Because the TMS does not sign payloads with a cryptographic signature (no HMAC, no X-Signature header), the recommended approach is:

1. Use a strong secret in the Authorization header. Treat the Authorization value as a shared secret — use a long, randomly generated token and validate it on every request.
2. Validate over HTTPS only. This ensures the Authorization header cannot be observed in transit.
3. Return 401 Unauthorized for requests with missing or incorrect credentials. The TMS will log the response code but will not retry.

---

Error Handling & Logging

Delivery Behavior

The TMS makes a single attempt to deliver each webhook. There is no automatic retry. If your endpoint is unavailable, times out, or returns an error status code, the event is logged and no further delivery is attempted.

Important: The TMS does not distinguish between 2xx and non-2xx responses for retry purposes. A 500 from your endpoint is logged just like a 200 — no re-delivery is attempted either way. To signal a real problem, you must proactively monitor WebhookActivityLogs yourself.

Your endpoint should respond quickly. Long-running processing should be dequeued asynchronously — accept the webhook, return 200 OK immediately, and process in the background.

Webhook Activity Logs

Every delivery attempt — successful or not — is written to the WebhookActivityLogs table in the TMS logging database, joined with the ApiDetails table via ApiDetailId. This is the primary tool for diagnosing integration issues.

Log Fields

"When an HTTP response was received" means any status code — 2xx, 3xx, 4xx, or 5xx all count. Fields are absent only when a network-level exception prevented a response entirely.

Reading the Logs

A few common patterns when investigating a failed delivery:

The webhook fired but my endpoint returned a 401

• ErrorMessage will be null — an HTTP response was received.
• ApiDetail.HttpStatusCode will be 401.
• ApiDetail.Request will contain the exact JSON that was sent.
• Check that the Authorization (or Basic) source setting value matches what your endpoint expects.

The webhook fired but I received nothing

• If ApiDetail.Response is empty and ApiDetail.HttpStatusCode is 200, your endpoint returned an empty body — that is fine.
• If ErrorMessage is populated, a network-level failure occurred before any HTTP response was received. The error message will indicate the cause (e.g., "No such host is known", "The operation was canceled").

The webhook never appeared in logs

• The triggering event may not have matched the linked organization on the Source Setting. Verify the shipment/customer/carrier belongs to the linked org.
• For shipment webhooks, the triggering event may still be within the ~1-minute batching window — wait and re-check.
• For ShipmentLocationUpdateUrl and ShipmentLocationUpdateExtendedUrl, confirm the 15-minute throttle window has elapsed since the last successful delivery.
• Because of the log-batching described below, expect up to a ~10-second delay before a delivery attempt is queryable.

Log Persistence and Batching

Webhook activity logs are flushed to the logging database in batches. A flush occurs when any of these conditions are met:

This means a log entry may not appear in the database immediately — expect up to a ~10-second delay before a delivery attempt is queryable in the logs.