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.

FieldTypeMeaning
idstringStable event UUID. Repeated deliveries of the same event have the same value.
typestringVersioned event type, such as file_action.activity.v1 or sync_run.failure.v1.
occurred_atstringISO 8601 timestamp of the underlying activity.
site_idintegerSite that produced the event.
workspace_idintegerWorkspace of the event; 0 identifies the Default Workspace.
severitystringSeverity in lowercase. See the event type mapping.
actorobject, optionalUser associated with the event, when available. Can contain id, username, and email; file activity can omit the email or user details.
resourcesarray of objectsRelated resources. Entries identify a type with an id or, for file activity, a path.
payloadobjectEvent-specific data described below.
humanobject, optionalHuman-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.

PathExample valueApplies to
typefile_action.activity.v1All events
severityinfoAll events
workspace_id0All events
actor.usernameintegration-userEvents with an associated user
payload.actioncreateFile activity
payload.pathincoming/orders.csvFile activity
payload.statusfailureEvents with an operational status
payload.sync_nameImport ordersSync runs with a named Sync
payload.automation_nameProcess ordersAutomation runs with a named Automation
human.titleFile activityEvents 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 Method

files_sdk.event_record.list()

Return Object

ListObj[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 files_sdk

try:
  event_records = files_sdk.event_record.list()
  for event_record in event_records.auto_paging_iter():
    print(event_record.get_attributes())
except files_sdk.error.NotAuthenticatedError as err:
  print(f"Authentication Error Occurred ({type(err).__name__}):", err)
except files_sdk.error.Error as err:
  print(f"Unknown Error Occurred ({type(err).__name__}):", err)

Show Event Record

SDK Method

files_sdk.event_record.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.

Method Arguments

ArgumentDescription
id
int64
Required		Event Record ID.

Example Request

import files_sdk

try:
  event_record = files_sdk.event_record.find(id)
  # Operate on event_record
except files_sdk.error.NotAuthenticatedError as err:
  print(f"Authentication Error Occurred ({type(err).__name__}):", err)
except files_sdk.error.Error as err:
  print(f"Unknown Error Occurred ({type(err).__name__}):", err)

The EventRecord Object

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

AttributeDescription
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.