Event Notifications

Webhook Event

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.
  • Invoice and payment events (*_INVOICE_CREATED, *_PAYMENT_CREATED) are sent by email, in-app and SMS only, not by webhook. To follow bills, invoices and payments, poll their /filter endpoints by updatedAt.

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
postWebhookyour-endpoint

Payload

sentAtstring date-time required

ISO 8601 timestamp when the webhook was sent from MVMNT

Example payload

{
  "sentAt": "2025-01-15T14:30:00Z",
  "events": [
    {
      "timestamp": "2025-01-15T14:30:00Z",
      "diff": [
        {
          "key": "status",
          "embeddedKey": "id",
          "value": "INACTIVE",
          "oldValue": "ACTIVE"
        }
      ]
    }
  ]
}

Response

Webhook received and processed successfully

Changes

Webhooks have no change history: a webhook is keyed by its event name rather than a path and method, so no recorded change can name it.