Document events

Alvys sends a webhook event when a document is uploaded to, or deleted from, a load, trip, driver, carrier, truck, or trailer. Use these events to copy documents into your system without polling the list-documents endpoints.

Event	Fires when	Holder key in `data`
`load.document.uploaded`	A document is uploaded to a load	`loadNumber`
`load.document.deleted`	A document is deleted from a load	`loadNumber`
`trip.document.uploaded`	A document is uploaded to a trip	`tripId`
`trip.document.deleted`	A document is deleted from a trip	`tripId`
`driver.document.uploaded`	A document is uploaded to a driver	`driverId`
`driver.document.deleted`	A document is deleted from a driver	`driverId`
`carrier.document.uploaded`	A document is uploaded to a carrier	`carrierId`
`carrier.document.deleted`	A document is deleted from a carrier	`carrierId`
`truck.document.uploaded`	A document is uploaded to a truck	`truckId`
`truck.document.deleted`	A document is deleted from a truck	`truckId`
`trailer.document.uploaded`	A document is uploaded to a trailer	`trailerId`
`trailer.document.deleted`	A document is deleted from a trailer	`trailerId`

Subscribe to each event by its exact name. There is no wildcard. The full list of valid event-type strings is returned by GET /api/p/v1.0/webhooks/event-types.

When document events fire

Uploaded fires when a document is first saved. In rare cases it can fire again for the same document, so deduplicate on data.document.id.
Deleted fires when a document is removed.
A rename, or a change to the document type, sends no event. For example, a call to Change load document type or Change trip document type sends nothing. If you need the current name and type, read the documents again with the list-documents endpoint.

Payload

Document events use the standard Alvys webhook envelope. The envelope version is v1. data has two fields:

The holder key from the table above (for example loadNumber). It identifies the record the document belongs to.
document, an object that describes the document.

Property names are camelCase. Fields with a null value are omitted, except the top-level subsidiaryId. For document events, the envelope id has the form {documentId}-{etag}. Treat the id as an opaque string. Use it only to deduplicate, and do not parse it.

The `document` object

Field	Type	Present	Description
`id`	string	Always	The document id.
`attachmentPath`	string	Always (can be `""`)	The stored file name of the document.
`attachmentType`	string	Always (can be `""`)	The display name of the document type, for example `Bill of Lading`, `Rate Confirmation`, `Proof of Delivery`, or `Other`. This is a string, not an enum. Accept values that you do not recognize.
`attachmentSize`	integer	Omitted if unknown	The file size in bytes.
`uploadedAt`	datetime	Omitted if unknown	When the document was uploaded.
`parentId`	string	Always	The id of the record the document is stored against. For trip documents, this is the load number. See Trip documents.
`parentType`	string	Always	One of `Load`, `Trip`, `Driver`, `Carrier`, `Truck`, `Trailer`.
`uploadedBy`	string	Omitted if unknown	The id of the user who uploaded the document.
`downloadUrl`	string	`*.uploaded` only	A link to download the file. It is valid for 10 minutes. Omitted on `*.deleted`.
`expiresAt`	datetime	`*.uploaded` only	When `downloadUrl` stops working. Omitted on `*.deleted`.

Download links expire after 10 minutes

downloadUrl is valid for 10 minutes from the time Alvys builds the event, not from the time your endpoint receives it. Alvys builds the event one time. Each retry sends the same body, so a retry can carry a link that has already expired. If expiresAt is in the past, or the download fails, get a fresh link from the list-documents endpoint for the holder:

Load: GET /api/p/v2.0/loads/{loadNumber}/documents (List load documents)
Trip: List trip documents
Driver: List driver documents
Carrier: List carrier documents
Truck: List truck documents
Trailer: List trailer documents

Start the download as soon as you receive the event. Do not store downloadUrl for later use.

Trip documents

For trip document events, the two identifiers are different:

data.tripId is the trip id.
data.document.parentId is the load number of the trip’s load, not the trip id.

Use data.tripId to find the trip.

Carrier documents go to every webhook

A carrier has no Subsidiary. For carrier.document.uploaded and carrier.document.deleted:

The envelope subsidiaryId is always null.
Alvys sends the event to every webhook in the tenant that subscribes to it, whatever Subsidiaries the webhook covers.

The other document events are matched on the Subsidiary of the load, trip, driver, truck, or trailer. See Which events reach your subscription.

Examples

{
  "id": "e2b9f6d4-8a1c-4e3b-b7d5-0c9f2a6e3d18-2e00d4f5-0000-0300-0000-6726f3d40000",
  "type": "load.document.uploaded",
  "timestamp": "2026-11-04T18:01:33+00:00",
  "version": "v1",
  "etag": "2e00d4f5-0000-0300-0000-6726f3d40000",
  "subsidiaryId": "2d7e4c19-5a3b-4f8e-b1d6-7c9a0e3f5b42",
  "data": {
    "loadNumber": "1008222",
    "document": {
      "id": "e2b9f6d4-8a1c-4e3b-b7d5-0c9f2a6e3d18",
      "attachmentPath": "BOL_1008222.pdf",
      "attachmentType": "Bill of Lading",
      "attachmentSize": 284113,
      "uploadedAt": "2026-11-04T18:01:33+00:00",
      "parentId": "1008222",
      "parentType": "Load",
      "uploadedBy": "9f4b2d71-6c3e-4a85-b0d9-2e7f1a5c8b36",
      "downloadUrl": "https://files.example.com/d/e2b9f6d4-8a1c-4e3b-b7d5-0c9f2a6e3d18?token=...",
      "expiresAt": "2026-11-04T18:11:34.5512+00:00"
    }
  }
}

{
  "id": "e2b9f6d4-8a1c-4e3b-b7d5-0c9f2a6e3d18-2f00e506-0000-0300-0000-6727a1e50000",
  "type": "load.document.deleted",
  "timestamp": "2026-11-05T09:14:02+00:00",
  "version": "v1",
  "etag": "2f00e506-0000-0300-0000-6727a1e50000",
  "subsidiaryId": "2d7e4c19-5a3b-4f8e-b1d6-7c9a0e3f5b42",
  "data": {
    "loadNumber": "1008222",
    "document": {
      "id": "e2b9f6d4-8a1c-4e3b-b7d5-0c9f2a6e3d18",
      "attachmentPath": "BOL_1008222.pdf",
      "attachmentType": "Bill of Lading",
      "attachmentSize": 284113,
      "uploadedAt": "2026-11-04T18:01:33+00:00",
      "parentId": "1008222",
      "parentType": "Load",
      "uploadedBy": "9f4b2d71-6c3e-4a85-b0d9-2e7f1a5c8b36"
    }
  }
}

{
  "id": "4c7a1e93-6b2d-4f80-a3c5-9e1d7b0f2a64-3000f617-0000-0300-0000-6726f4e50000",
  "type": "trip.document.uploaded",
  "timestamp": "2026-11-04T19:10:00+00:00",
  "version": "v1",
  "etag": "3000f617-0000-0300-0000-6726f4e50000",
  "subsidiaryId": "2d7e4c19-5a3b-4f8e-b1d6-7c9a0e3f5b42",
  "data": {
    "tripId": "9a3d5e71-2c84-4b1f-a6e9-3f0b7d2c8e14",
    "document": {
      "id": "4c7a1e93-6b2d-4f80-a3c5-9e1d7b0f2a64",
      "attachmentPath": "POD_1008222-1.pdf",
      "attachmentType": "Proof of Delivery",
      "attachmentSize": 512330,
      "uploadedAt": "2026-11-04T19:10:00+00:00",
      "parentId": "1008222",
      "parentType": "Trip",
      "downloadUrl": "https://files.example.com/d/4c7a1e93-6b2d-4f80-a3c5-9e1d7b0f2a64?token=...",
      "expiresAt": "2026-11-04T19:20:01.03+00:00"
    }
  }
}

{
  "id": "7d2f0b85-1e6c-4a39-8b74-c5a9e3d1f026-3100a728-0000-0300-0000-6726f5f60000",
  "type": "driver.document.uploaded",
  "timestamp": "2026-11-04T20:00:00+00:00",
  "version": "v1",
  "etag": "3100a728-0000-0300-0000-6726f5f60000",
  "subsidiaryId": "2d7e4c19-5a3b-4f8e-b1d6-7c9a0e3f5b42",
  "data": {
    "driverId": "5b8e2c4f-0a7d-4913-b6e2-8f1c3d9a7e50",
    "document": {
      "id": "7d2f0b85-1e6c-4a39-8b74-c5a9e3d1f026",
      "attachmentPath": "medical_card.pdf",
      "attachmentType": "Medical Card",
      "uploadedAt": "2026-11-04T20:00:00+00:00",
      "parentId": "5b8e2c4f-0a7d-4913-b6e2-8f1c3d9a7e50",
      "parentType": "Driver",
      "downloadUrl": "https://files.example.com/d/7d2f0b85-1e6c-4a39-8b74-c5a9e3d1f026?token=...",
      "expiresAt": "2026-11-04T20:10:00.7+00:00"
    }
  }
}

{
  "id": "8e3a1c96-2f7d-4b4a-9c85-d6b0f4e2a137-3200b839-0000-0300-0000-6727b2f60000",
  "type": "carrier.document.deleted",
  "timestamp": "2026-11-05T10:00:00+00:00",
  "version": "v1",
  "etag": "3200b839-0000-0300-0000-6727b2f60000",
  "subsidiaryId": null,
  "data": {
    "carrierId": "a1b2c3d4-e5f6-4789-a0b1-c2d3e4f5a6b7",
    "document": {
      "id": "8e3a1c96-2f7d-4b4a-9c85-d6b0f4e2a137",
      "attachmentPath": "coi_2026.pdf",
      "attachmentType": "Certificate of Insurance (COI)",
      "parentId": "a1b2c3d4-e5f6-4789-a0b1-c2d3e4f5a6b7",
      "parentType": "Carrier"
    }
  }
}

truck.document.* and trailer.document.* events have the same shape as the driver example, with truckId or trailerId in place of driverId. The examples show these points:

On load.document.deleted, downloadUrl and expiresAt are absent. They are not sent as null.
On trip.document.uploaded, uploadedBy is absent because it is unknown. parentId is the load number.
On carrier.document.deleted, subsidiaryId is null. Fields such as attachmentSize and uploadedAt are absent because they are unknown.

Notes

Delivery is at-least-once. Deduplicate on X-Alvys-Event-Id. See Event Delivery & Reliability.
Document events do not carry a data.diff node.
Load and trip changes send their own events. See Load events and Trip events.

Getting Started

Delivery & Security

Events

Webhook API

Secrets

Delivery Logs & Health

Document events

When document events fire

Payload

The `document` object

Download links expire after 10 minutes

Trip documents

Carrier documents go to every webhook

Examples

Notes

​When document events fire

​Payload

​The document object

​Download links expire after 10 minutes

​Trip documents

​Carrier documents go to every webhook

​Examples

​Notes

When document events fire

Payload

The `document` object

Download links expire after 10 minutes

Trip documents

Carrier documents go to every webhook

Examples

Notes