Skip to content
API Reference/Event Notifications/
Webhook Event

MVMNT API (1.0.0)

The MVMNT API enables you to automate freight brokerage workflows by integrating directly with our Transportation Management System.

Authentication

OAuth 2.0 client credentials flow. See Authentication Guide for details.

Token Endpoint

POST https://api.mvmnt.io/oauth2/token

Request

Headers:

Content-Type: application/x-www-form-urlencoded

Body Parameters:

grant_type=client_credentials
client_id=YOUR_CLIENT_ID
client_secret=YOUR_CLIENT_SECRET

Example Request

curl -X POST https://api.mvmnt.io/oauth2/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=client_credentials" \
  -d "client_id=YOUR_CLIENT_ID" \
  -d "client_secret=YOUR_CLIENT_SECRET"

Success Response

Status: 200 OK

{
  "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "Bearer",
  "expires_in": 3600
}

Response Fields:

  • access_token: JWT Bearer token to use for API requests
  • token_type: Always Bearer
  • expires_in: Token lifetime in seconds (3600 = 1 hour)
Download OpenAPI description
openapi.json
openapi.yaml
Overview
URL
https://docs.mvmnt.io
MVMNT Support
support@mvmnt.io
License
Proprietary
Languages
Servers
Mock server
https://docs.mvmnt.io/_mock/apis/openapi/
Production
https://api.mvmnt.io/v1/

Companies

Operations

Carrier Contacts

Operations

Carriers

Operations

Carrier Factors

Operations

Carrier Payment Methods

Operations

Customer Contacts

Operations

Customers

Operations

Locations

Operations

Location Contacts

Operations

Payment Terms

Operations

Teams

Operations

Users

Operations

Vendors

Operations

Vendor Contacts

Operations

Vendor Payment Methods

Operations

Saved Searches

Operations

Event Notifications

Webhooks

Webhook EventWebhook

Request

All webhook events are delivered to your configured endpoint URL.

The event field in the payload determines which type of webhook was triggered. Your endpoint should handle all event types or gracefully ignore unknown events.

Event Types:

  • Entity changes: CUSTOMER_*, COMPANY_*, CARRIER_*, CUSTOMER_CONTACT_*
  • Shipment events: SHIPMENT_DELIVERED, SHIPMENT_BOOKED, SHIPMENT_DISPATCHED, etc.
  • Financial events: CARRIER_INVOICE_CREATED, CUSTOMER_PAYMENT_CREATED, etc.

Security: All webhook requests include an x-api-key header containing your webhook token configured in the MVMNT UI.

Best Practices:

  • Return 200 OK quickly and process asynchronously
  • Implement idempotency using event ID and timestamp
  • Handle unknown event types gracefully for forward compatibility
Security
BearerAuth
Bodyapplication/jsonrequired
sentAtstring(date-time)required

ISO 8601 timestamp when the webhook was sent from MVMNT

Example: "2025-01-15T14:30:00Z"
eventsArray of objects(WebhookPayload)non-emptyrequired

Array of webhook events (typically contains a single event)

events[].​eventstringrequired

The type of webhook event

Enum"CUSTOMER_CREATED""CUSTOMER_UPDATED""CUSTOMER_DELETED""CARRIER_ACTIVATED""CARRIER_CONTACT_CREATED""CARRIER_CONTACT_UPDATED""CARRIER_CONTACT_DELETED""CARRIER_CREATED""CARRIER_DEACTIVATED""CARRIER_DELETED"
Discriminator
events[].​timestampstring(date-time)required

ISO 8601 timestamp when the event occurred

Example: "2025-01-15T14:30:00Z"
events[].​dataobject(Customer)required
events[].​data.​objectstringread-only

Object type identifier

Value"CUSTOMER"
Example: "CUSTOMER"
events[].​data.​idstring(uuid)read-onlyrequired

Unique customer identifier

Example: "550e8400-e29b-41d4-a716-446655440000"
events[].​data.​namestringrequired

Customer company name

Example: "Acme Manufacturing Corp"
events[].​data.​friendlyIdstringread-onlyrequired

Human-readable customer identifier, starts with "A"

Example: "A123456"
events[].​data.​statusstringrequired

Customer account status (includes lead stages):

  • NEW: New lead, not yet contacted
  • CONTACTED: Initial contact made with lead
  • QUALIFIED: Lead has been qualified as potential customer
  • QUOTED: Quote has been provided to lead
  • NURTURING: Lead being nurtured for future opportunity
  • PENDING: Customer prospect pending activation
  • ACTIVE: Active customer account
  • INACTIVE: Deactivated customer account
  • BLOCKED: Customer account blocked from operations
  • CLOSED: Customer account permanently closed
Enum"NEW""CONTACTED""QUALIFIED""QUOTED""NURTURING""PENDING""ACTIVE""INACTIVE""BLOCKED""CLOSED"
events[].​data.​serviceTierCustomerServiceTier (string) or null
Any of:

Service tier level for the customer

string CustomerServiceTier Recursive
events[].​data.​websitestring or null or string or null

Customer website URL

Example: "https://acme-manufacturing.com"
events[].​data.​phoneNumberstring or null or string or null

Primary phone number

Example: "+1-555-123-4567"
events[].​data.​industryCustomerIndustry (string) or null
Any of:

Industry classification for the customer

string CustomerIndustry Recursive
events[].​data.​annualRevenueCustomerAnnualRevenue (string) or null
Any of:

Annual revenue range

string CustomerAnnualRevenue Recursive
events[].​data.​annualSpendCustomerAnnualSpend (string) or null
Any of:

Annual freight spend estimate range

string CustomerAnnualSpend Recursive
events[].​data.​spendTypeCustomerSpendType (string) or null
Any of:

Customer spend type:

  • CONTRACT: Customer operates under contract pricing
  • SPOT: Customer operates on spot market pricing
string CustomerSpendType Recursive
events[].​data.​naicsstring or null or string or null

NAICS industry code

Example: "336411"
events[].​data.​einstring or null or string or null

Employer Identification Number

Example: "12-3456789"
events[].​data.​dunsstring or null or string or null

Dun & Bradstreet number

Example: "123456789"
events[].​data.​leadSourcestring or null or string or null

How this customer was acquired

Example: "Referral"
events[].​data.​dbaNamestring or null or string or null

Doing business as name

Example: "Acme Corp DBA"
events[].​data.​numberOfEmployeesCustomerNumberOfEmployees (string) or null
Any of:

Number of employees in the company

string CustomerNumberOfEmployees Recursive
events[].​data.​externalIdstring or null or string or null

External system identifier

Example: "EXT-12345"
events[].​data.​currencyCustomerCurrency (string) or null
Any of:

Preferred currency for transactions

string CustomerCurrency Recursive
events[].​data.​creditLimitnumber or null or number or null(float)

Maximum credit allowed

Example: 50000
events[].​data.​creditUsageWarningnumber or null or number or null(float)

Credit usage warning threshold

Example: 40000
events[].​data.​freeCreditReqnumber or null or number or null(float)

Free credit requirement

Example: 5000
events[].​data.​defaultModeCustomerTransportationMode (string) or null
Any of:

Transportation mode type

string CustomerTransportationMode Recursive
events[].​data.​defaultMarginnumber or null or number or null(float)

Default margin percentage (0-1, e.g., 0.15 for 15%)

Example: 0.15
events[].​data.​minMarginnumber or null or number or null(float)

Minimum margin threshold

Example: 0.1
events[].​data.​maxMarginnumber or null or number or null(float)

Maximum margin threshold

Example: 0.25
events[].​data.​defaultInternalNotesstring or null or string or null

Default internal notes template

Example: "Contact via email only"
events[].​data.​defaultExternalNotesstring or null or string or null

Default external notes template

Example: "Please call 1 hour before delivery"
events[].​data.​autoAcceptTenderboolean or null or boolean or null

Auto-accept tender flag

Example: false
events[].​data.​groupResourceReference (object) or null
Any of:

Reference to another resource (returned in responses)

object ResourceReference Recursive
events[].​data.​paymentTermPaymentTermReference (object) or null
Any of:

Enhanced reference to a payment term resource (returned in responses). Includes full payment term details in addition to id/key.

object PaymentTermReference Recursive
events[].​data.​notesstring or null or string or null

Internal notes about this customer

Example: "Prefers email communication"
events[].​data.​deactivationReasonCustomerDeactivationReason (string) or null
Any of:

Reason for customer deactivation:

  • NOT_PAYING_INVOICE: Customer is not paying invoices
  • ACQUIRED: Customer was acquired by another company
  • DUPLICATE: Duplicate customer record
  • NOT_IN_BUSINESS: Customer is no longer in business
  • OTHER: Other reason (see deactivationNotes for details)
string CustomerDeactivationReason Recursive
events[].​data.​deactivationNotesstring or null or string or null

Additional details about deactivation

events[].​data.​deactivationDatestring or null or string or null(date-time)

When the customer was deactivated

Example: null
events[].​data.​closedAtstring or null or string or null(date-time)

When the customer account was closed

Example: null
events[].​data.​closedByUserReference (object) or nullread-only
Any of:

Enhanced reference to a user resource (returned in responses). Includes full user details in addition to id/key.

Note: Does NOT include nested references (teams, etc.) to prevent recursion. Maximum nesting depth: 1 level.

object UserReference Recursive
events[].​data.​closedNotesstring or null or string or null

Notes about account closure

events[].​data.​corporateAddressAddress (object) or null
Any of:

Physical address/location details (nested, without id).

This is an embedded object representing a Location record. The id is managed internally and not exposed in the API.

object Address Recursive
events[].​data.​billingAddressAddress (object) or null
Any of:

Physical address/location details (nested, without id).

This is an embedded object representing a Location record. The id is managed internally and not exposed in the API.

object Address Recursive
events[].​data.​qboCustomerIdstring or null or string or null

QuickBooks Online customer ID

Example: null
events[].​data.​keystring or null or string or null<= 512 characters

Client-defined reference identifier for this customer

Example: "ERP-CUSTOMER-12345"
events[].​data.​contactsArray of objects(CustomerContactReference)

Contacts for this customer

events[].​data.​createdAtstring(date-time)read-onlyrequired

Timestamp when customer was created

Example: "2025-01-15T10:00:00Z"
events[].​data.​updatedAtstring(date-time)read-onlyrequired

Timestamp when customer was last updated

Example: "2025-01-15T14:30:00Z"
events[].​data.​deletedAtstring or null or string or null(date-time)read-only

Timestamp when customer was soft-deleted (null if active)

Example: null
events[].​data.​deletedByUserReference (object) or nullread-only
Any of:

Enhanced reference to a user resource (returned in responses). Includes full user details in addition to id/key.

Note: Does NOT include nested references (teams, etc.) to prevent recursion. Maximum nesting depth: 1 level.

object UserReference Recursive
events[].​data.​property name*anyadditional property
events[].​diffArray of objects or null(DiffChange)

Array of changes made during an UPDATE operation using json-diff-ts. Only present for UPDATE events. Null for CREATE and DELETE events. Each change follows the IChange interface from json-diff-ts library.

application/json
{
  "sentAt": "2025-01-15T14:30:05Z",
  "events": [
    { … }
  ]
}

Responses

Webhook received and processed successfully