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 Method

event_record.List()

Return Values

Returns a *event_record.Iter and an error. Range over All() to receive files_sdk.EventRecord values and errors. Check each loop error before using its resource. Next() and Err() remain supported.

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 (
    "fmt"
    "errors"

    files_sdk "github.com/Files-com/files-sdk-go/v3"
    event_record "github.com/Files-com/files-sdk-go/v3/eventrecord"
)

eventRecordIterator, err := event_record.List(files_sdk.EventRecordListParams{})
if err != nil {
    var respErr files_sdk.ResponseError
    if errors.As(err, &respErr) {
        fmt.Printf("API error (%s): %s\n", respErr.Type, respErr.ErrorMessage)
    } else {
        fmt.Printf("Request failed: %v\n", err)
    }
    return
}

for eventRecord, err := range eventRecordIterator.All() {
    if err != nil {
        var respErr files_sdk.ResponseError
        if errors.As(err, &respErr) {
            fmt.Printf("API error (%s): %s\n", respErr.Type, respErr.ErrorMessage)
        } else {
            fmt.Printf("Request failed: %v\n", err)
        }
        return
    }
    fmt.Println(eventRecord)
}

Show Event Record

SDK Method

event_record.Find()

Return Values

Returns a files_sdk.EventRecord value and an error.

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.

EventRecordFindParams Fields

Field	Description
Id int64 Required	Event Record ID.

Example Request

import (
    "fmt"
    "errors"

    files_sdk "github.com/Files-com/files-sdk-go/v3"
    event_record "github.com/Files-com/files-sdk-go/v3/eventrecord"
)

eventRecord, err := event_record.Find(files_sdk.EventRecordFindParams{Id: 1})
if err != nil {
    var respErr files_sdk.ResponseError
    if errors.As(err, &respErr) {
        fmt.Printf("API error (%s): %s\n", respErr.Type, respErr.ErrorMessage)
    } else {
        fmt.Printf("Request failed: %v\n", err)
    }
    return
}
fmt.Println(eventRecord)

The EventRecord Object

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

Attribute	Description
Id int64	Event Record ID
WorkspaceId int64	Workspace ID. 0 means the default workspace or site-wide.
EventUuid string	Stable event UUID.
EventType 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`
SourceType string	Source record type.
SourceId int64	Source record ID.
OccurredAt date-time	Event occurrence date/time.
HumanTitle string	Human-readable event title.
HumanSummary string	Human-readable event summary.
HumanFields 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.
CreatedAt date-time	Event Record create date/time.

Event Records

Event Delivery Payload

Verifying Webhook Deliveries

Custom Field Paths

List Event Records

SDK Method

Return Values

Authorization Requirement

Additional Arguments

Pagination

Sorting

Filtering

Show Event Record

SDK Method

Return Values

Authorization Requirement

EventRecordFindParams Fields

The EventRecord Object