Event Records

An EventRecord is a durable event emitted by Files.com for routing through Event Channels.

Event Delivery Payload

Event Channels deliver this JSON event object as the webhook request body, the Amazon SNS message, or the Google Pub/Sub message data. For SNS or Pub/Sub, first unwrap the service's delivery envelope and decode its message data as required by that service.

This delivery object differs from the Event Record object returned by the API. Its id is the event's UUID, corresponding to the API object's event_uuid, rather than the API object's numeric id. Use the delivery id as your idempotency key across retries and subscriptions. Delivery order is not guaranteed; occurred_at identifies the event's time, rather than the time your receiver received it.

Field	Type	Meaning
`id`	string	Stable event UUID. Repeated deliveries of the same event have the same value.
`type`	string	Versioned event type, such as `file_action.activity.v1` or `sync_run.failure.v1`.
`occurred_at`	string	ISO 8601 timestamp of the underlying activity.
`site_id`	integer	Site that produced the event.
`workspace_id`	integer	Workspace of the event; `0` identifies the Default Workspace.
`severity`	string	Severity in lowercase. See the event type mapping.
`actor`	object, optional	User associated with the event, when available. Can contain `id`, `username`, and `email`; file activity can omit the email or user details.
`resources`	array of objects	Related resources. Entries identify a `type` with an `id` or, for file activity, a `path`.
`payload`	object	Event-specific data described below.
`human`	object, optional	Human-readable `title`, `summary`, and optional `fields`. Each fields entry has a `label` and a string `value`. Available details vary by event.

For file activity, payload contains action, path, resource_type, and interface, with src and destination when applicable. For operational events, it contains the source record's id and created_at, with completed_at and status when applicable. Related Syncs and Automations supply sync_id and sync_name, or automation_id and automation_name. Expectation events supply the Expectation identity, window timing, and evaluation or incident details. Error details, user information, and links to further details depend on the event type and available data. Read machine fields for routing and processing; human-readable text serves display purposes.

Verifying Webhook Deliveries

Webhook requests include X-Files-Event-Id and X-Files-Event-Type, matching the body's id and type. When the target has a signing secret, verify X-Files-Signature-V2: compute HMAC-SHA256 over the exact received body bytes using that secret, then compare its lowercase hexadecimal digest with the header using a constant-time comparison. The digest has no sha256= prefix. Verify before parsing the JSON; reserializing it changes the bytes. See Webhook Signatures for configuration and verification examples.

Custom Field Paths

Subscription Custom Field filters read this same event object. A dot separates nested object keys. Paths depend on the selected event types; a field absent from an event has no value. Array indexes and wildcards are not supported.

Path	Example value	Applies to
`type`	`file_action.activity.v1`	All events
`severity`	`info`	All events
`workspace_id`	`0`	All events
`actor.username`	`integration-user`	Events with an associated user
`payload.action`	`create`	File activity
`payload.path`	`incoming/orders.csv`	File activity
`payload.status`	`failure`	Events with an operational status
`payload.sync_name`	`Import orders`	Sync runs with a named Sync
`payload.automation_name`	`Process orders`	Automation runs with a named Automation
`human.title`	`File activity`	Events with a human-readable title

Example File Activity Delivery

{
  "id": "91e0b57b-62b7-4f4e-b935-0cc8d6632054",
  "type": "file_action.activity.v1",
  "occurred_at": "2026-11-09T10:15:00Z",
  "site_id": 123,
  "workspace_id": 0,
  "severity": "info",
  "actor": {
    "id": 456,
    "username": "integration-user"
  },
  "resources": [
    {
      "type": "file",
      "path": "incoming/orders.csv"
    }
  ],
  "payload": {
    "action": "create",
    "path": "incoming/orders.csv",
    "resource_type": "file",
    "interface": "sftp"
  },
  "human": {
    "title": "File activity",
    "summary": "incoming/orders.csv: 1 uploaded"
  }
}

List Event Records

SDK Function

EventRecord.list()

Return Object

ListIterator<EventRecord>

Authorization Requirement

Requires a Site-Wide API key, or a User API key or session from a Site Administrator or a Workspace Administrator for the relevant workspace.

Additional Arguments

Example Request

import com.files.ListIterator;
import com.files.exceptions.*;
import com.files.exceptions.ApiErrorException.*;
import com.files.models.EventRecord;

try {
  HashMap<String, Object> parameters = new HashMap<>();
  ListIterator<EventRecord> eventRecords = EventRecord.list(parameters);
  for (EventRecord eventRecord : eventRecords.listAutoPaging()) {
    // Operate on eventRecord
  }
} catch (NotAuthenticatedException e) {
  System.out.println("Authentication Error Occurred (" + e.getClass().getName() + "): " + e.getMessage());
} catch (SdkException e) {
  System.out.println("Unknown Error Occurred (" + e.getClass().getName() + "): " + e.getMessage());
}

Show Event Record

SDK Function

EventRecord.find()

Return Object

EventRecord

Authorization Requirement

Requires a Site-Wide API key, or a User API key or session from a Site Administrator or a Workspace Administrator for the relevant workspace.

Function Arguments

Argument	Description
id int64 Required	Event Record ID.

Example Request

import com.files.exceptions.*;
import com.files.exceptions.ApiErrorException.*;
import com.files.models.EventRecord;

try {
  HashMap<String, Object> parameters = new HashMap<>();
  EventRecord eventRecord = EventRecord.find(id, parameters);
  // Operate on eventRecord
} catch (NotAuthenticatedException e) {
  System.out.println("Authentication Error Occurred (" + e.getClass().getName() + "): " + e.getMessage());
} catch (SdkException e) {
  System.out.println("Unknown Error Occurred (" + e.getClass().getName() + "): " + e.getMessage());
}

The EventRecord Object

Some of the functions above return a EventRecord object. The attributes of this object are listed below.

Attribute	Description
id int64	Event Record ID
workspace_id int64	Workspace ID. 0 means the default workspace or site-wide.
event_uuid string	Stable event UUID.
event_type string	Versioned event type string. Valid values: `automation_run.canceled.v1`, `automation_run.failure.v1`, `automation_run.failure_will_retry.v1`, `automation_run.partial_failure.v1`, `automation_run.partial_failure_will_retry.v1`, `automation_run.skipped.v1`, `automation_run.success.v1`, `expectation_evaluation.invalid.v1`, `expectation_evaluation.late.v1`, `expectation_evaluation.missing.v1`, `expectation_evaluation.success.v1`, `expectation_incident.acknowledged.v1`, `expectation_incident.open.v1`, `expectation_incident.resolved.v1`, `expectation_incident.snoozed.v1`, `external_event.client_log.failure.v1`, `external_event.client_log.partial_failure.v1`, `external_event.client_log.skipped.v1`, `external_event.client_log.success.v1`, `malware_scan_log.quarantined.v1`, `pending_work_event.failure.v1`, `pending_work_event.partial_failure.v1`, `pending_work_event.skipped.v1`, `pending_work_event.success.v1`, `siem_http_destination_event.failure.v1`, `siem_http_destination_event.partial_failure.v1`, `siem_http_destination_event.skipped.v1`, `siem_http_destination_event.success.v1`, `sso_event.ldap_login.failure.v1`, `sso_event.ldap_login.partial_failure.v1`, `sso_event.ldap_login.skipped.v1`, `sso_event.ldap_login.success.v1`, `sso_event.ldap_sync.failure.v1`, `sso_event.ldap_sync.partial_failure.v1`, `sso_event.ldap_sync.skipped.v1`, `sso_event.ldap_sync.success.v1`, `sso_event.saml_login.failure.v1`, `sso_event.saml_login.partial_failure.v1`, `sso_event.saml_login.skipped.v1`, `sso_event.saml_login.success.v1`, `sync_run.failure.v1`, `sync_run.partial_failure.v1`, `sync_run.skipped.v1`, `sync_run.success.v1`, `user_security_event.lockout.v1`
severity string	Event severity. Possible values: `info`, `warning`, `error`, `critical`
source_type string	Source record type.
source_id int64	Source record ID.
occurred_at date-time	Event occurrence date/time.
human_title string	Human-readable event title.
human_summary string	Human-readable event summary.
human_fields array(object)	Human-readable event detail fields.
actor object	Actor associated with the event.
resources array(object)	Resources associated with the event.
payload object	Event payload.
created_at date-time	Event Record create date/time.

Event Records

Event Delivery Payload

Verifying Webhook Deliveries

Custom Field Paths

List Event Records

SDK Function

Return Object

Authorization Requirement

Additional Arguments

Pagination

Sorting

Filtering

Show Event Record

SDK Function

Return Object

Authorization Requirement

Function Arguments

The EventRecord Object