Webhook Integration Guide

Table of Contents

• Overview
• Webhook Events
• Payload Schemas
• Authentication
• Error Handling & Logging

---

Overview

The TAI TMS webhook system allows your application to receive real-time 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
      ▼
Serialize payload (camelCase JSON)
      │
      ▼
POST to configured URL
      │
      ▼
Log result to WebhookActivityLog

Key Behaviors

Versioning

The Version source setting controls the shape of shipment payloads and how statuses are represented.

If no Version is configured, the system defaults to version 3.

---

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: Shipment record is persisted for the first time.
• Payload: Full shipment details (ShipmentDetails).
• Notes: Fires once per shipment, immediately on creation.

---

ShipmentDetailUpdateUrl

Fires when an existing shipment's details are modified.

• Trigger: Any update to shipment information — stops/addresses, commodities, accessorials, carrier assignment, reference numbers, etc.
• Payload: Full shipment details (ShipmentDetails), reflecting the state after the update.
• Notes: Can fire multiple times over the life of a shipment. This does not fire for status-only changes (see ShipmentStatusUpdateUrl).

---

ShipmentStatusUpdateUrl

Fires when a shipment's status changes.

• Trigger: A shipment transitions to a new status (e.g., Quote → Committed, Committed → InTransit, InTransit → Delivered).

• Payload: Full shipment details (ShipmentDetails) including the new status value.

• Throttle: Fires at most once every 15 minutes per shipment, per linked organization. If a status update occurs within the 15-minute window of the previous one, it is suppressed until the window expires.

• Status values by version:

  Version	"Booked" status sent as	"Quoting" status sent as
  2	Booked	Quoted
  3 (default)	Committed	Quote

---

ShipmentLocationUpdateUrl

Fires when a new GPS/location update is received for a shipment — but only if enough time has elapsed since the last update.

• Trigger: A location update is recorded for an in-transit shipment.
• Payload: Simplified shipment data focused on location — shipment ID, status, latitude, longitude, location string, and last location update timestamp.
• Throttle: Fires at most once every 15 minutes per shipment. If a location ping arrives within 15 minutes of the previous webhook delivery, it is silently dropped.
• Notes: This webhook is specifically designed for high-frequency location tracking scenarios. The 15-minute throttle prevents flooding your endpoint with every GPS ping.

---

Accounting Events

BillCreateUrl

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

• Trigger: A carrier/vendor bill completes the approval workflow step.
• Payload: Full bill details (PublicAPIBill) including line items, payment status, and external sync details.
• Delivery timing: Dispatched via a background job with a ~5-second delay after the approval action.
• Notes: The payload includes the payer organization, vendor, line items, and any existing payment applications. The bill's payerOrganizationId is used to match the webhook's linked organization.

---

CommissionBillCreateUrl

Fires when a commission bill is approved through the Approve Bill workflow.

• Trigger: A commission record completes the approval workflow step.
• Payload: Commission details (PublicAPICommission), which mirrors the bill structure but represents agent/rep commissions.
• Notes: Structurally identical to BillCreateUrl but scoped to commission-type billing records.

---

InvoiceCreateUrl

Fires when an invoice is finalized.

• Trigger: The Invoice Create process completes for a customer invoice.
• Payload: Invoice details only (PublicAPIInvoice) — organization info, line items, payment status, due dates, recipients.
• 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 in the payload.

• Trigger: The Invoice Create process completes for a customer invoice.
• Payload: A composite object containing both invoice (PublicAPIInvoice) and shipmentDetails (ShipmentDetails).
• Notes: Use this instead of InvoiceCreateUrl when your downstream system needs to correlate invoice financials with the full shipment record in a single call. InvoiceCreateUrl and InvoiceCreateWithShipmentUrl should not both be configured on the same Source Setting — they fire for the same event.

---

Customer Events

CustomerCreateUrl

Fires when a new customer organization is created in the TMS.

• Trigger: A customer organization record is persisted for the first time.
• Payload: Customer organization details (PublicAPIOrganization) — name, addresses, contact info, reference number, and metadata.
• Notes: Scoped to the parent organization hierarchy of the webhook's linked organization. Only customers that belong to the linked org's hierarchy will trigger this webhook.

---

CustomerUpdateUrl

Fires when an existing customer organization's record is modified.

• Trigger: Any field update on a customer organization (name, address, phone, reference number, notes, etc.).
• Payload: Full updated customer details (PublicAPIOrganization).
• Notes: Same organization hierarchy scoping as CustomerCreateUrl. Not every internal state change triggers this — it fires on direct record edits.

---

Carrier Events

LSPCarrierCreateUrl

Fires when a new carrier is added to the TMS.

• Trigger: A broker carrier (LSP carrier) record is created.
• Payload: Carrier details (PublicAPILSPCarrier) including carrier master info, insurance records, supported trailer types, contacts, payment preferences, and labels.

---

LSPCarrierUpdateUrl

Fires when an existing carrier record is modified.

• Trigger: Any update to a broker carrier record — contact info, insurance, payment terms, supported equipment, labels, status, etc.
• Payload: Full updated carrier details (PublicAPILSPCarrier).

---

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.

The sections below map each webhook URL type to its payload shape. Nested object types are defined once and cross-referenced where reused.

---

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 exactly, representing agent or rep commissions rather than carrier/vendor bills.

Commission

---

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

⚠️

Deprecated. Version 1 payloads are no longer recommended. Use Version 3 (default) for all new integrations.

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

All webhook requests are sent over HTTPS. The TMS enforces TLS 1.0, 1.1, and 1.2. Endpoints that do not support HTTPS or present an invalid certificate will cause the request to fail and be logged as an error. There is no TLS pinning; standard OS certificate store validation applies.

Recommendation: Require TLS 1.2 or higher on your endpoint and reject any plain HTTP connections.

---

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.

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.

Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ=

The encoding uses ASCII. 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 static Authorization value is applied first, but the Basic auth header is set afterward and overwrites it. The effective header sent will be the Authorization: Basic ... value.

---

Verifying Requests Are From the TMS

Because the TMS does not sign payloads with a cryptographic signature, the recommended approach for endpoint verification is:

1. Use a 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.

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. This is the primary tool for diagnosing integration issues.

Log Fields

"On success only" here means an HTTP response was received — any status code counts. Fields are absent only when a network-level exception prevented a response entirely (DNS failure, connection refused, timeout, TLS error).

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 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 ShipmentStatusUpdateUrl and ShipmentLocationUpdateUrl, confirm the 15-minute throttle window has elapsed since the last delivery.

---

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.