> ## Documentation Index
> Fetch the complete documentation index at: https://docs.truv.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Document Collection Webhook Events
> Webhook events for document collection file processing and categorization
Subscribe to these events via [Webhooks](/api-reference/webhooks) to track document collection processing in real time, instead of polling the [collection retrieve endpoint](/api-reference/document-collections/collections_retrieve).
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`](#documents-preprocessed) 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`](/api-reference/tasks/events#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](/api-reference/document-collections/object#uploaded-file-attributes).
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:
```json theme={null}
{
"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:
```json theme={null}
{
"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) |
```json theme={null}
{
"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
}
```