Events reference

The File Service publishes these events through the Notification Service, with source: "files". How to receive them is on Events. Every event arrives in the Notification Service’s envelope, with id, type, source, tenant_id, application_id, payload and the time it was published; see the event envelope. Payloads carry ids and names, never bytes, text or URLs.

file.ready

Processing of a version finished.

{ "file_id": "01J9Z6S9Q5F5R6Y2W2GZ3B3K4D", "name": "IMG_5913.jpg", "kind": "image", "folder_id": "root", "external_ref": "post:123",
  "version_no": 1, "renditions": ["thumbnail", "preview", "large"],
  "processing": { "sniff": "done", "policy": "done", "hash": "done", "scan": "clean", "metadata": "done", "sanitize": "done", "renditions": "done", "text": "skipped", "publish": "skipped", "notify": "pending" } }

• Recipients: the owner, the uploader when it is a user, and the ticket’s notify_user_ids.
• Push: none.
• renditions lists the renditions that are ready.

file.failed

Processing refused the file (its type did not match, its type is not allowed, its checksum differed), or a step failed and processing stopped there.

{ "file_id": "01J9Z6S9Q5F5R6Y2W2GZ3B3K4D", "name": "invoice.pdf", "step": "sniff", "error": "type_mismatch" }

• Recipients: the same as file.ready.
• Push: none.
• error is type_mismatch, type_not_allowed, hash_mismatch, or the failed step’s error.
• step: "scan" when the scan could not finish and the application does not serve unscanned files (scan_failed_policy: block): the file stays, but is never served.

file.quarantined

Malware scanning found the file infected. The file is never served again; its renditions, public copy and share links are removed.

{ "file_id": "01J9Z6S9Q5F5R6Y2W2GZ3B3K4D", "name": "setup.zip", "signature": "the name of what was found" }

• signature is present when the scanner named what it found.
• Recipients: the owner, and the users who manage access to the file (a user entry with share on it or its folders).
• Push: when they are offline, “A file was quarantined”.

file.status.changed

The approval status changed.

{ "file_id": "01J9Z6S9Q5F5R6Y2W2GZ3B3K4D", "name": "contract.pdf", "from": "draft", "to": "in_review", "by_user_id": "user-ana" }

• Recipients: the owner (unless they made the change); on in_review also the users who may approve the file.
• Push: when they are offline, to the approvers on in_review (“A file needs review”) and to the owner on approved and rejected.

file.shared

A user was given an access entry on a file or folder.

{ "file_id": "01J9Z6S9Q5F5R6Y2W2GZ3B3K4D", "name": "brochure.pdf", "entry": { "principal": { "type": "user", "user_id": "user-ben" }, "actions": ["view", "download"] } }

• For a folder, the payload has folder_id instead of file_id.
• Recipients: the user of the entry. Role and application entries publish nothing.
• Push: when they are offline, “someone shared name with you”.

file.version.created

A new version became current.

{ "file_id": "01J9Z6S9Q5F5R6Y2W2GZ3B3K4D", "name": "brochure.pdf", "version_no": 3, "by_user_id": "user-ben" }

• Recipients: the owner, when someone else uploaded the version.
• Push: none.

folder.changed

Something changed in a folder.

{ "folder_id": "01J9Z6T1A0B4C9D8E7F6G5H4J3", "change": "created", "item": { "type": "file", "id": "01J9Z6S9Q5F5R6Y2W2GZ3B3K4D", "name": "IMG_5913.jpg" } }

• change is created, renamed, moved, trashed, restored or updated; item names the child that changed, when there is one.
• Recipients: the subscribers of the topic files:folder:<folder_id>, which the service creates with the folder. An app subscribes while the folder is open.
• Push: none.

Webhooks

The same events reach your backend as signed HTTPS calls to one endpoint per application, with the same payloads inside the envelope { id, type, source, tenant_id, application_id, payload, published_at }, a ping when the webhook is saved, retries, and an X-Files-Signature header that FilesClient.verifyWebhookSignature of the Node client checks. See Webhooks.