Events
The File Service publishes events through the CCS Notification Service, to the users they concern. Your app receives them on the same live stream it already uses for Chat or for your own events. This page explains who gets what and how; every payload is on Events reference.
What is published
Section titled “What is published”| Event | When | Who receives it |
|---|---|---|
file.ready |
Processing of a version finished | The owner, the uploader, and the ticket’s notify_user_ids |
file.failed |
Processing refused the file or a step failed | The same |
file.quarantined |
Malware scanning found it infected | The owner and the users who manage access to the file, with a push when they are offline |
file.status.changed |
The approval status changed | The owner; on in_review also the users who may approve it, with a push when they are offline |
file.shared |
A user was given an access entry | That user, with a push when they are offline |
file.version.created |
A new version became current | The owner, when someone else uploaded it |
folder.changed |
Something was created, renamed, moved, trashed or restored in a folder | Everyone subscribed to the folder’s topic |
Every event has source: "files", the tenant_id and application_id, and a payload with ids and names only: never bytes, text or URLs. A client mints its own URL with its own rights.
Receiving them in your app
Section titled “Receiving them in your app”Your app uses the Notification Service’s user client, with a token from its own token route; see the Notification Service’s integration guide. Filter on the source:
notifications.realtime.on('file.ready', (event) => swapInPreview(event.payload.file_id), { source: 'files' });notifications.realtime.on('file.failed', (event) => showUploadError(event.payload.file_id, event.payload.error), { source: 'files' });For a live folder listing, subscribe to the folder’s topic files:folder:<folder_id> with the user client’s setTopics while the folder is open, and reload the listing on folder.changed. The service creates the topic with the folder. See topics.
Receiving them in your backend
Section titled “Receiving them in your backend”A backend cannot subscribe to a user’s stream. It receives the same events through a webhook: one signed HTTPS call per event to an endpoint of your backend, configured per application, retried when your endpoint does not answer, and verified with FilesClient.verifyWebhookSignature of the Node client. See Webhooks.
Without a webhook, your backend polls (the Node client’s files.files.waitUntilReady(fileId), or GET P/files/:file_id and its processing), or does not need to know: it renders the original until the preview exists (see Feeds and batch URL minting).
Delivery rules
Section titled “Delivery rules”- Events are best effort: a write never fails because an event could not be published. Treat them as hints and read the file when one arrives.
- A webhook delivery is at least once: de-duplicate on the event’s
id. - Each event has a stable idempotency key (the event, the item and its revision), so a retried publish is delivered once.
- The Notification Service delivers only to active members of the tenant, and replays missed events after a reconnect within its retention window. See realtime.