1. Shipment Documents
  • Introduction
  • Getting Started
  • Authentication
  • Error Handling
  • Contact Support
  • Modaltrans API
    • Get Auth Token
      • Get Bearer Token
    • Accounting
      • Invoices
        • Retrieve an Invoice
        • List all Invoices
      • Invoice Items
        • List all Invoice Items
        • Deleted Invoice Items
      • Financials
        • Retrieve Financial Information
    • Customs
      • NCTS Declarations
        • List all NCTS Declarations
        • Retrieve an NCTS Declaration
        • Create an NCTS Declaration with XML Data
        • Update an NCTS Declaration
        • Download an NCTS Declaration
        • List Timelines of NCTS Declaration
        • List Messages of NCTS Decalaration
      • Customs Declarations
        • List all Customs Declarations
        • Retrieve a Custom Declaration
        • Create a Customs Declaration
        • Update a Custom Declaration
        • Delete a Custom Declaration
        • Retrieve a Declaration History
        • Retrieve an MRN Status of Declaration
      • Declaration Requests
        • List all Declaration Orders
        • Retrieve a Declaration Request
        • Create a Declaration Request
        • Update a Declaration Request
        • Delete a Declaration Request
      • Ens Declarations
        • Create an Ens Declaration
        • Download an Ens Declaration
    • Logistics
      • Bookings
        • Retrieve a Booking
        • List all Bookings
        • Create a Booking
        • Update a Booking
      • Locations
        • List all Locations
        • Retrieve a Location
      • Positions
        • Update a Transport
        • Get All Positions
        • Retrieve a Position
      • Tracking
        • Available Shipping Lines
        • Retrieve a Tracking Data
        • Subscribe to Tracking
      • Shipments
        • Retrieve a Shipment
        • List All Shipments
        • Retrieve Financials of Shipment
        • List Contacts of the Shipment
        • Create a Shipment
        • Update a Shipment
      • Tariffs
        • List All Tariffs
        • Retrieve a Tariff
        • Create a Tariff
        • Update a Tariff
        • Download a Tariff PDF
    • Depot
      • Orders
        • Retrieve an Order
        • List all Orders
        • Create an Order
        • Update an Order
      • Products
        • Retrieve a Product
        • List all Products
        • Create a Product
        • Update a Product
        • List Product Stocks
      • Inventories
        • List all Inventories
    • Fleet Management
      • Drivers
        • Retrieve a Driver
        • Retrieve a Driver's Vehicle
        • List Driver Positions
        • Update a Driver
      • Vehicles
        • Retrieve a Vehicle
        • Update a Vehicle
      • Gps Service Controller
        • Create Gps Responses
      • Service Logs
        • List all Service Logs
        • Retrieve a Service Log
        • Create a Service Log
        • Delete a Service Log
        • Update a Service Log
      • Periodic Documents
        • Retrieve a Periodic Document
        • Update a Periodic Document
        • Create a Periodic Document
    • CRM
      • Companies
        • List all Companies
        • Retrieve a Company
        • Create a Company
        • Update a Company
        • Delete a Company
        • List Company Credit Limits
      • Quotes
        • Retrieve a Quote
        • List All Quotes
        • Update a Quote
        • Create a Quote
        • Accept a Quote
        • Reject a Quote
    • Timelines
      • Retrieve a Timeline
      • List Timelines
      • Create a Timeline
    • S3 Files
      • List all S3Files
      • Create an S3File
      • Delete an S3File
    • Notifications
      • List all Notifications
      • Update a Notification Status
    • User Details
      • List User Details
      • Update User Details
    • Milestones
      • Retrieve a Milestone
      • List Milestones
      • Create a Milestone
      • Delete a Milestone
      • Update a Milestone
  • Webhooks
    • Webhooks
    • Trackings
      • Tracking Webhooks
      • Sea
        • Sea Tracking Event Created
        • Sea Tracking Event Updated
      • Air
        • Air Tracking Event Created
        • Air Tracking Event Updated
    • Customs
      • Customs Declaration Status Changed
      • NCTS Declaration Status Changed
      • ENS Declaration Status Changed
      • GVMS Declaration Status Changed
    • Shipment Documents
      • Shipment Document Webhooks
      • Shipment Document Created
      • Shipment Document Updated
  1. Shipment Documents

Shipment Document Webhooks

Shipment document events tell you when a document is attached to one of your shipments, or when a document on one of your shipments changes. They carry the details of the document, not the file itself: you download the file through the API when you need it.
How an endpoint is created, how to check the signature, how to answer and what we retry is the same for every Modaltrans webhook and is described on the Webhooks page. This page covers the shipment document events and how to fetch the file.

Events#

In Modaltrans, both events are under Logistics > Shipment document in the endpoint's Subscribed Events.
EventSent when
shipment_documents/createA file is attached to one of your shipments
shipment_documents/updateThe name, the file class or the visibility of a document on one of your shipments changes
Each page above carries the headers, the full payload schema and a worked example.
data holds one document. parent_type is always Logistics::Loading, and parent_id is the numeric id of the shipment, the same value as transaction_id in the shipments API. auth_code says who can see the document in Modaltrans: 1 is Everybody, the customer portal included, and 0 is Our Team Only, your own users. Every key is always sent. A missing value comes as null, except parent_customer_ref, which comes as an empty string when the shipment has no customer reference.
The payload shows the document as it stands when the delivery is built, shortly after the change, so two changes that land close together can both arrive with the later values. Retries and resends reuse that body unchanged.

Matching documents to your records#

eventKey in the envelope identifies the document. It is the same on its create and on every update that follows, so upsert on it. deliveryId is unique per delivery and only repeats on a retry or a resend of that same delivery, so de-duplicate on it. These events have no eventID and no modaltrans object.
An update can arrive for a document you have no record of yet, for example one attached before the endpoint was created. Treat it as a create.

Downloading the file#

The webhook carries no file content and no download link. To fetch the file, call List all S3Files with parent_type and parent_id from the payload:
The response lists the documents of that shipment, each with a document_url. Pick the one whose id matches data[0].id and download the file from its document_url. The link is signed and short-lived, so ask for the list right before you download rather than storing the URL. A test delivery, the one with test set to true, carries made-up ids that match no real document, so skip the download for it.

Modified at 2026-11-18 13:57:11
Previous
GVMS Declaration Status Changed
Next
Shipment Document Created
Built with