Document Collection Webhook Events

Subscribe to these events via Webhooks to track document collection processing in real time, instead of polling the collection retrieve endpoint. Both events include these common fields:

Field	Description
`webhook_id`	Unique identifier for this webhook request
`event_type`	The event classification
`event_created_at`	Timestamp when the event occurred
`user_id`	Associated Truv user identifier

user_id is the user a file or document belongs to — null when none is associated yet. document-collection-preprocessing-completed is the exception: it carries a users array instead. These events cover preprocessing — validation and AI categorization of uploaded files. They do not cover finalization. Finalization creates Links and Tasks; track that with task-status-updated.

Document status updated

Event type: document-collection-file-status-updated Fires every time an uploaded file changes status — not just when it reaches a final state — so you can show live progress. See the full list of file statuses in the Document Collections object. These fields appear in every payload:

Field	Description
`collection_id`	The collection the file belongs to
`file_id`	The uploaded file whose status changed
`status`	New file status: `validating`, `validated`, `invalid`, `duplicate`, `processing`, `successful`, or `failed`
`documents`	Documents recognized from this file (empty until categorization completes)

Each entry in documents contains:

Field	Description
`document_id`	The recognized document identifier
`document_type`	Recognized type, valid values: `PAYSTUB`, `W2`, `F1099`, `F1040`, `BANK_STATEMENT`, `PASSPORT`, `GREEN_CARD`, `DRIVER_LICENSE`, `LETTER_OF_VERIFICATION`, `UTILITY_BILL`, `LEASE_AGREEMENT`, `INSURANCE_HOME_POLICY`, `INSURANCE_AUTO_POLICY`, `VOLUNTEER_LETTER`, `OTHER`
`document_subtype`	Recognized subtype (nullable), valid values: `F1099_MISC`, `F1099_NEC`, `F1099_DIV`, `F1099_INT`, `F1099_G`, `F1099_R`, `F_SSA1099`, `VOL_TRANSCRIPT`, `VOL_HOURS_LOG`
`user_id`	The user this document belongs to (nullable)
`start_page`	First page of the document within the file (nullable)
`end_page`	Last page of the document within the file (nullable)

An early update, before categorization runs — documents is empty:

{
  "webhook_id": "1a2b3c4d5e6f708192a3b4c5d6e7f809",
  "event_type": "document-collection-file-status-updated",
  "event_created_at": "2026-07-06T12:34:50Z",
  "user_id": "b7d3f0a9c1e24d6fa8b3c2d1e0f9a8b7",
  "collection_id": "a1b2c3d4e5f60718293a4b5c6d7e8f90",
  "file_id": "c3d4e5f60718293a4b5c6d7e8f90a1b2",
  "status": "validating",
  "documents": []
}

A file that has finished categorization — documents is populated:

{
  "webhook_id": "9f8c2a1b4d5e6f708192a3b4c5d6e7f8",
  "event_type": "document-collection-file-status-updated",
  "event_created_at": "2026-07-06T12:34:56Z",
  "user_id": "b7d3f0a9c1e24d6fa8b3c2d1e0f9a8b7",
  "collection_id": "a1b2c3d4e5f60718293a4b5c6d7e8f90",
  "file_id": "c3d4e5f60718293a4b5c6d7e8f90a1b2",
  "status": "successful",
  "documents": [
    {
      "document_id": "d4e5f60718293a4b5c6d7e8f90a1b2c3",
      "document_type": "PAYSTUB",
      "document_subtype": null,
      "user_id": "b7d3f0a9c1e24d6fa8b3c2d1e0f9a8b7",
      "start_page": 1,
      "end_page": 1
    },
    {
      "document_id": "e5f60718293a4b5c6d7e8f90a1b2c3d4",
      "document_type": "F1099",
      "document_subtype": "F1099_NEC",
      "user_id": "b7d3f0a9c1e24d6fa8b3c2d1e0f9a8b7",
      "start_page": 2,
      "end_page": 2
    }
  ]
}

Documents preprocessed

Event type: document-collection-preprocessing-completed Fires once per collection, right after the last file finishes processing — every file has reached a final status. Use it to know that validation and categorization are done for the whole collection. This is not the same as finalized. It means every file has been validated and categorized. Whether the collection turns into employer records and Tasks depends on your settings and can happen later.

If a user later uploads more files to the same collection, this event fires again once those files finish processing.

A collection can belong to more than one user, so this event carries a users array instead of the common single user_id field.

Field	Description
`users`	Ids of all users associated with the collection (empty if none)
`collection_id`	The collection that finished preprocessing
`total_file_count`	Total number of files in the collection
`successful_file_count`	Files categorized successfully
`failed_file_count`	Files that did not succeed (invalid, duplicate, or failed)

{
  "webhook_id": "718293a4b5c6d7e8f90a1b2c3d4e5f60",
  "event_type": "document-collection-preprocessing-completed",
  "event_created_at": "2026-07-06T12:35:10Z",
  "users": ["b7d3f0a9c1e24d6fa8b3c2d1e0f9a8b7", "c8e4f1b0d2f35e7fb9c4d3e2f1a0b9c8"],
  "collection_id": "a1b2c3d4e5f60718293a4b5c6d7e8f90",
  "total_file_count": 3,
  "successful_file_count": 2,
  "failed_file_count": 1
}

API Reference

Platform

Income & Employment

Financial Accounts

Document Processing

Direct Deposit Switch

Insurance Verification

Document Collection Webhook Events

Document status updated

Documents preprocessed

​Document status updated

​Documents preprocessed

Document status updated

Documents preprocessed