Skip to main content
Question

V2 Webhook: When and how often does FILE.UPLOADED fire?

  • Oct 28, 2026 1:07 PM UTC
  • 1 reply
  • 13 views
  • Translate All
Forum|alt.badge.img

I have two questions about Box V2 Webhooks.

 

1. When is FILE.UPLOADED triggered?

When a new version of an existing file is created, is FILE.UPLOADED triggered for all of the following methods?

  • Uploading a new version through the Box web interface

  • API (POST /files/{id}/content)

  • Saving through Box Drive

  • Saving through Box Tools (Box Edit)

  • Editing through Box for Microsoft 365

  • Editing through Box for Google Workspace

2. How often does FILE.UPLOADED fire during autosave or collaborative editing?

When using Box for Microsoft 365 or Box for Google Workspace, is FILE.UPLOADED triggered every time a new file_version.id is created?

Is there a defined or typical interval between version updates?

I'm considering using webhooks for file synchronization and would like to understand the event frequency to avoid unnecessary processing.

Any clarification would be appreciated. Thank you!

1 reply

Jason S
Forum|alt.badge.img
  • Jason S
  • Box Employee
  • Oct 28, 2026 4:40 PM UTC

Hi ​@アリー, welcome to the Box Community! These are great questions to settle before building a file sync workflow.

1. When does FILE.UPLOADED fire?

FILE.UPLOADED is a folder-level V2 webhook trigger for a file uploaded or moved into the watched folder. It cannot be attached directly to a file.

How the file is updated Can it create a new Box file version? FILE.UPLOADED guidance
Upload New Version in the Box web interface Yes Expect a folder webhook when the version uploads
POST /files/{id}/content Yes Expect a folder webhook when the version uploads
Save through Box Drive Yes, when the change syncs to Box Expect a folder webhook when the version uploads
Save through Box Tools (Box Edit) Yes, when the save uploads successfully Expect a folder webhook when the version uploads
Edit through Box for Microsoft 365 Yes, when Box creates a version Validate webhook behavior for this editor
Edit through Box for Google Workspace Yes, when Box creates a version Validate webhook behavior for this editor

Our version-history documentation confirms these paths can create Box versions. Our webhook documentation does not explicitly guarantee one FILE.UPLOADED event for every new file_version.id across all six paths, so I would validate that relationship before relying on it for sync. Also, an event may reflect a file moved into the folder rather than a new upload.

2. How often during autosave or collaborative editing?

Editor What we document about Box version creation
Microsoft Office co-authoring A new version is created after five minutes since the last version, when a collaborator downloads the file within that period, or when a collaborator closes a co-authoring session. Versions can therefore occur less than five minutes apart.
Google Workspace Edits autosave back to Box, but I don’t have a published interval for new Box file_version.id values to share.

For synchronization, I recommend treating the webhook as a signal to check the file. Compare its current file_version.id with the last one you processed, and group rapid notifications by file ID to avoid repeat work. Deduplicate delivery retries using the webhook event id in the payload body; that ID stays the same across retries.

If you need to capture every intermediate version, please test each editor against a folder webhook and compare the events with Box version history. If you find a mismatch, contact Box Support with the webhook ID, folder ID, file ID, editing method, approximate times, version IDs, and event IDs so we can investigate it.

Translate
Terms of ServiceAccessibility statement