Event Reference - Flatfile Developer Docs

Flatfile emits events throughout the data import lifecycle, allowing your applications to respond to user actions, system changes, and processing results. This reference documents all available events, their payloads, and when they are triggered.

Event Structure

All Flatfile events follow a consistent structure. Optional fields may be included depending on the event’s Domain (workbook-level events, for instance, won’t have a sheetId)

interface FlatfileEvent {
  id: string;
  topic: string;
  domain: string;
  context: {
    environmentId: string;
    spaceId?: string;
    workbookId?: string;
    sheetId?: string;
    jobId?: string;
    fileId?: string;
    [key: string]: any;
  };
  payload: any;
  attributes?: any;
  createdAt: string;
}

Listening and Reacting to Events

To respond to these events, you’ll need to create a Listener that subscribes to the specific events your application needs to handle.

Job Events

Job events are triggered when background tasks and operations change state.

job:created

Triggered when a new job is first created. Some jobs will enter an optional planning state at this time. A job with ‘immediate’ set to true will skip the planning step and transition directly to ‘ready.‘

{
  domain: string       // event domain (e.g., "space", "workbook")
  operation: string    // operation name (e.g., "configure")
  job: string          // domain:operation format (e.g., "space:configure")
  status: string       // job status
  info?: string        // optional info message
  isPart: boolean      // whether this is a sub-job
  input?: any          // job input data
}

{
  accountId: string
  environmentId: string
  spaceId?: string
  jobId: string
  actorId: string
}

job:ready

Triggered when a job is ready for execution by your listener. Either the job has a complete plan of work or the job is configured to not need a plan. This is the only event most job implementations will care about. Once a ready job is acknowledged by a listener, it transitions into an executing state.

{
  domain: string       // event domain (e.g., "space", "workbook")
  operation: string    // operation name (e.g., "configure")
  job: string          // domain:operation format (e.g., "space:configure")
  status: string       // job status
  info?: string        // optional info message
  isPart: boolean      // whether this is a sub-job
  input?: any          // job input data
}

{
  accountId: string
  environmentId: string
  spaceId?: string
  jobId: string
  actorId: string
}

listener.filter({ job: "*" }, (configure) => {
  configure.on("job:ready", async (event) => {
    const { jobId } = event.context
    // Handle any job that becomes ready
    await processJob(jobId)
  })
})

job:scheduled

Triggered when a job is scheduled to run at a future time

{
  domain: string       // event domain (e.g., "space", "workbook")
  operation: string    // operation name (e.g., "configure")
  job: string          // domain:operation format (e.g., "space:configure")
  status: string       // job status (scheduled)
  info?: string        // optional info message
  isPart: boolean      // whether this is a sub-job
  input?: any          // job input data
}

{
  accountId: string
  environmentId: string
  spaceId?: string
  jobId: string
  actorId: string
}

job:updated

Triggered when a job is updated. For example, when a listener updates the state or progress of the job. The event will emit many times as the listener incrementally completes work and updates the job.

{
  domain: string       // event domain (e.g., "space", "workbook")
  operation: string    // operation name (e.g., "configure")
  job: string          // domain:operation format (e.g., "space:configure")
  status: string       // job status
  info?: string        // optional info message
  isPart: boolean      // whether this is a sub-job
  input?: any          // job input data
}

{
  accountId: string
  environmentId: string
  spaceId?: string
  jobId: string
  actorId: string
}

job:completed

Triggered when a job has completed successfully

{
  domain: string       // event domain (e.g., "space", "workbook")
  operation: string    // operation name (e.g., "configure")
  job: string          // domain:operation format (e.g., "space:configure")
  status: string       // job status
  info?: string        // optional info message
  isPart: boolean      // whether this is a sub-job
  input?: any          // job input data
}

{
  accountId: string
  environmentId: string
  spaceId?: string
  jobId: string
  actorId: string
}

job:outcome-acknowledged

Triggered to trigger workflow actions after the user has acknowledged that the job has completed or failed. Background jobs will skip this step.

{
  domain: string       // event domain (e.g., "space", "workbook")
  operation: string    // operation name (e.g., "configure")
  job: string          // domain:operation format (e.g., "space:configure")
  status: string       // job status
  info?: string        // optional info message
  isPart: boolean      // whether this is a sub-job
  input?: any          // job input data
}

{
  accountId: string
  environmentId: string
  spaceId?: string
  workbookId?: string
  sheetId?: string
  jobId: string
  actorId: string
}

job:parts-completed

Triggered when all parts of a multi-part job have completed processing

{
  domain: string       // event domain (e.g., "space", "workbook")
  operation: string    // operation name (e.g., "configure")
  job: string          // domain:operation format (e.g., "space:configure")
  status: string       // job status (parts-completed)
  info?: string        // optional info message
  isPart: boolean      // whether this is a sub-job
  input?: any          // job input data
  parts: Array<{       // completed parts information
    partId: string
    status: string
    completedAt: string
  }>
}

{
  accountId: string
  environmentId: string
  spaceId?: string
  jobId: string
  actorId: string
}

job:failed

Triggered when a job fails

{
  domain: string       // event domain (e.g., "space", "workbook")
  operation: string    // operation name (e.g., "configure")
  job: string          // domain:operation format (e.g., "space:configure")
  status: string       // job status
  info?: string        // optional info message
  isPart: boolean      // whether this is a sub-job
  input?: any          // job input data
}

{
  accountId: string
  environmentId: string
  spaceId?: string
  workbookId?: string
  sheetId?: string
  jobId: string
  actorId: string
}

job:deleted

Triggered when a job is deleted

{
  accountId: string
  environmentId: string
  spaceId?: string
  jobId: string
  actorId: string
}

Program Events

Program events are triggered when mapping programs and transformations change state.

program:created

Triggered when a new mapping program is created

{}

{
  accountId: string
  environmentId: string
  spaceId: string
  workbookId: string
  sheetId: string
  actorId: string
}

program:updated

Triggered when a mapping program is updated

{}

{
  accountId: string
  environmentId: string
  spaceId: string
  workbookId: string
  sheetId: string
  actorId: string
}

program:recomputing

Triggered when a mapping program begins recomputing its transformations

{}

{
  accountId: string
  environmentId: string
  spaceId: string
  workbookId: string
  sheetId: string
  actorId: string
}

program:recomputed

Triggered when a mapping program has finished recomputing its transformations

{}

{
  accountId: string
  environmentId: string
  spaceId: string
  workbookId: string
  sheetId: string
  actorId: string
}

File Events

File events are triggered when files are uploaded, processed, or modified.

file:created

Triggered when a file upload begins or a new file is created

{
  accountId: string
  environmentId: string
  spaceId: string
  fileId: string
  actorId: string
}

file:updated

Triggered when a file is updated. For example, when a file has been extracted into a workbook

{
  accountId: string
  environmentId: string
  spaceId: string
  fileId: string
  actorId: string
}

{
  status: string
  workbookId?: string
}

file:deleted

Triggered when a file is deleted

{
  accountId: string
  environmentId: string
  spaceId: string
  fileId: string
  actorId: string
}

file:expired

Triggered when a file is expired

{
  accountId: string
  environmentId: string
  spaceId: string
  fileId: string
}

Record Events

Record events are triggered when data records are created, updated, or deleted.

records:created

Triggered when new records are added to a sheet

{
  sheetId: string
  recordIds: string[]
  recordCount: number
}

{
  environmentId: string
  spaceId: string
  workbookId: string
  sheetId: string
}

records:updated

A note on commit:created vs records:updatedYou might think you want to listen to records:updated for data processing, but commit:created is the recommended choice for most automation.A commit is like a “git commit” but for data - a versioned snapshot of all changes that occurred together in a single operation. This provides complete transaction context and better performance when processing multiple record changes.Flatfile’s own Plugins (Record Hooks, Constraints, Autocast, etc.) all use commit:created. Reserve records:updated only for real-time per-record feedback scenarios.

Triggered when existing records are modified

{
  sheetId: string
  recordIds: string[]
  changes: Array<{
    recordId: string
    fieldKey: string
    previousValue: any
    newValue: any
  }>
}

records:deleted

Triggered when records are deleted from a sheet

{
  sheetId: string
  recordIds: string[]
  recordCount: number
}

Sheet Events

Sheet events are triggered when sheets are created, modified, or when sheet-level operations occur.

sheet:calculation-updated

Triggered when sheet calculations or formulas are updated

{
  sheetId: string
  workbookId: string  
  calculations: Array<{
    field: string
    formula: string
    updated: boolean
  }>
}

{
  accountId: string
  environmentId: string
  spaceId: string
  workbookId: string
  sheetId: string
  actorId: string
}

sheet:counts-updated

Triggered when record counts for a sheet are updated

{
  sheetId: string
  workbookId: string
  counts: {
    total: number
    valid: number
    error: number
    updated: number
  }
}

{
  accountId: string
  environmentId: string
  spaceId: string
  workbookId: string
  sheetId: string
  actorId: string
}

sheet:created

Triggered when a new sheet is created

{
  sheetId: string
  workbookId: string
  name: string
  slug: string
  fieldCount: number
}

sheet:updated

Triggered when a sheet Blueprint or configuration is modified

{
  sheetId: string
  workbookId: string
  changes: Array<{
    type: "field_added" | "field_removed" | "field_updated" | "config_updated"
    details: any
  }>
}

sheet:deleted

Triggered when a sheet is deleted

{
  sheetId: string
  workbookId: string
  name: string
  slug: string
}

Workbook Events

Workbook events are triggered for workbook-level operations and changes.

workbook:created

Triggered when a new workbook is created

{
  workbookId: string
  spaceId: string
  name: string
  namespace?: string
  sheetCount: number
}

workbook:updated

Triggered when a workbook is modified

{
  workbookId: string
  spaceId: string
  changes: Array<{
    type: "sheet_added" | "sheet_removed" | "config_updated"
    details: any
  }>
}

workbook:deleted

Triggered when a workbook is deleted

{
  workbookId: string
  spaceId: string
}

workbook:expired

Triggered when a workbook expires

{
  workbookId: string
  spaceId: string
}

Space Events

Space (Project) events are triggered for project lifecycle changes.

space:created

Triggered when a new project (space) is created

{
  spaceId: string
  environmentId: string
  name: string
  appId?: string
}

space:updated

Triggered when a project is modified

{
  spaceId: string
  environmentId: string
  changes: Array<{
    field: string
    previousValue: any
    newValue: any
  }>
}

space:deleted

Triggered when a space is deleted

{
  accountId: string
  environmentId: string
  spaceId: string
  workbookId: string
  actorId: string
}

space:expired

Triggered when a space is expired

{
  accountId: string
  environmentId: string
  spaceId: string
  workbookId: string
}

space:archived

Triggered when a space is archived

{
  accountId: string
  environmentId: string
  spaceId: string
}

space:guestAdded

Triggered when a guest is added

{
  actorId: string
  accountId: string
  environmentId: string
  spaceId: string
}

space:guestRemoved

Triggered when a guest’s access is revoked from a space

{
  actorId: string
  accountId: string
  environmentId: string
  spaceId: string
}

space:unarchived

Triggered when a space is unarchived and restored to active status

{}

{
  actorId: string
  accountId: string
  environmentId: string
  spaceId: string
}

Environment Events

Environment events are triggered for organization-level changes.

environment:autobuild-created

Triggered when an autobuild configuration is created for an environment

{}

{
  environmentId: string
  accountId: string
  appId?: string
  actorId: string
}

environment:created

Triggered when a new environment is created

{
  environmentId: string
  name: string
  slug: string
  isProd: boolean
}

environment:updated

Triggered when an environment is modified

{
  environmentId: string
  changes: Array<{
    field: string
    previousValue: any
    newValue: any
  }>
}

environment:deleted

Triggered when an environment is deleted

{
  environmentId: string
  deletedAt: string
  deletedBy: string
}

Action Events

Action events are triggered when custom actions are created, updated, or deleted.

action:created

Triggered when a new custom action is created

{
  actionId: string
  name: string
  label: string
  description?: string
  type: string
}

{
  accountId: string
  environmentId: string
  spaceId: string
  workbookId?: string
  sheetId?: string
  actorId: string
}

action:updated

Triggered when a custom action is updated

{
  actionId: string
  name: string
  label: string
  description?: string
  type: string
  changes: Array<{
    field: string
    previousValue: any
    newValue: any
  }>
}

{
  accountId: string
  environmentId: string
  spaceId: string
  workbookId?: string
  sheetId?: string
  actorId: string
}

action:deleted

Triggered when a custom action is deleted

{
  actionId: string
  name: string
}

{
  accountId: string
  environmentId: string
  spaceId: string
  workbookId?: string
  sheetId?: string
  actorId: string
}

Document Events

Document events are triggered when documents are created, updated, or deleted within workbooks.

document:created

Triggered when a document is created on a workbook

{
  actorId: string
  spaceId: string
  accountId: string
  documentId: string
  environmentId: string
}

document:updated

Triggered when a document is updated on a workbook

{
  actorId: string
  spaceId: string
  accountId: string
  documentId: string
  environmentId: string
}

document:deleted

Triggered when a document is deleted on a workbook

{
  actorId: string
  spaceId: string
  accountId: string
  documentId: string
  environmentId: string
}

Commit Events

Commit events are triggered when data changes are made to records.

commit:created

Triggered when a cell in a record is created or updated

{
  sheetId: string
  workbookId: string
  versionId: string
  sheetSlug: string
}

commit:updated

Triggered when commit metadata or details are updated

{
  sheetId: string
  workbookId: string
  commitId: string
  versionId: string
  changes: Array<{
    field: string
    previousValue: any
    newValue: any
  }>
}

{
  accountId: string
  environmentId: string
  spaceId: string
  workbookId: string
  sheetId: string
  actorId: string
}

commit:completed

Triggered when a commit has completed (only when trackChanges is enabled)

{
  sheetId: string
  workbookId: string
  versionId: string
  commitId: string
}

layer:created

Triggered when a new layer is created within a commit

{
  sheetId: string
  workbookId: string
  layerId: string
  commitId: string
}

Snapshot Events

Snapshot events are triggered when snapshots of sheet data are created.

snapshot:created

Triggered when a snapshot is created of a sheet

{
  snapshotId: string
  sheetId: string
  workbookId: string
  spaceId: string
}

Agent Events

Agent events are triggered when agents are created, updated, or deleted.

agent:created

Triggered when a new agent is deployed

{
  agentId: string
  environmentId: string
}

agent:updated

Triggered when an agent is updated

{
  agentId: string
  environmentId: string
}

agent:deleted

Triggered when an agent is deleted

{
  agentId: string
  environmentId: string
}

Secret Events

Secret events are triggered when secrets are managed.

secret:created

Triggered when a new secret is created

{
  secretId: string
  spaceId: string
  environmentId: string
}

secret:updated

Triggered when a secret is updated

{
  secretId: string
  spaceId: string
  environmentId: string
}

secret:deleted

Triggered when a secret is deleted

{
  secretId: string
  spaceId: string
  environmentId: string
}

Data Clip Events

Data clip events are triggered when data clips are managed.

data-clip:collaborator-updated

Triggered when collaborators are added or removed from a data clip

{
  dataClipId: string
  collaborators: string[]
  changes: Array<{
    action: "added" | "removed"
    userId: string
  }>
}

{
  accountId: string
  environmentId: string
  spaceId: string
  dataClipId: string
}

data-clip:created

Triggered when a new data clip is created

{
  dataClipId: string
  accountId: string
  status: string
}

data-clip:updated

Triggered when a data clip’s details are updated

{
  dataClipId: string
  accountId: string
  status: string
}

data-clip:deleted

Triggered when a data clip is deleted

{
  dataClipId: string
  accountId: string
  status: string
}

data-clip:resolutions-created

Triggered when new conflict resolutions are created for a data clip

{
  dataClipId: string
  resolutions: Array<{
    conflictId: string
    resolution: any
    resolvedBy: string
  }>
}

{
  accountId: string
  environmentId: string
  spaceId: string
  dataClipId: string
}

data-clip:resolutions-refreshed

Triggered when conflict resolutions are refreshed or recalculated for a data clip

{}

{
  accountId: string
  environmentId: string
  spaceId: string
  dataClipId: string
}

data-clip:resolutions-updated

Triggered when existing conflict resolutions are updated for a data clip

{
  dataClipId: string
  resolutions: Array<{
    conflictId: string
    resolution: any
    resolvedBy: string
    updatedAt: string
  }>
  changes: Array<{
    conflictId: string
    previousResolution: any
    newResolution: any
  }>
}

{
  accountId: string
  environmentId: string
  spaceId: string
  dataClipId: string
}

Canvas Events

Canvas events are triggered when canvases are created, updated, or deleted.

canvas:created

Triggered when a new canvas is created

{
  // Full canvas object with all properties
}

{
  canvasId: string
  spaceId: string
  environmentId: string
  accountId: string
}

canvas:updated

Triggered when a canvas is updated

{
  // Full canvas object with all properties
}

{
  canvasId: string
  spaceId: string
  environmentId: string
  accountId: string
}

canvas:deleted

Triggered when a canvas is deleted

{
  // Full canvas object with all properties
}

{
  canvasId: string
  spaceId: string
  environmentId: string
  accountId: string
}

Canvas Area Events

Canvas area events are triggered when canvas areas are created, updated, or deleted.

canvas-area:created

Triggered when a new canvas area is created

{
  // Full canvas area object with all properties
}

{
  canvasAreaId: string
  canvasId: string
}

canvas-area:updated

Triggered when a canvas area is updated

{
  // Full canvas area object with all properties
}

{
  canvasAreaId: string
  canvasId: string
}

canvas-area:deleted

Triggered when a canvas area is deleted

{
  // Full canvas area object with all properties
}

{
  canvasAreaId: string
  canvasId: string
}

Thread Events

Thread events are triggered when AI conversation threads are created, updated, or deleted.

thread:created

Triggered when a new AI conversation thread is created

{
  threadId: string
  title?: string
  status: string
  createdAt: string
}

{
  accountId: string
  environmentId: string
  spaceId: string
  threadId: string
  actorId: string
}

thread:updated

Triggered when an AI conversation thread is updated

{
  threadId: string
  title?: string
  status: string
  changes: Array<{
    field: string
    previousValue: any
    newValue: any
  }>
}

{
  accountId: string
  environmentId: string
  spaceId: string
  threadId: string
  actorId: string
}

thread:deleted

Triggered when an AI conversation thread is deleted

{}

{
  accountId: string
  environmentId: string
  spaceId: string
  threadId: string
  actorId: string
}

Cron Events

** Deployed Agents Required **Cron events are only created for environments that have deployed agents subscribed to the specific cron topics. These events will not fire in localhost development environments unless you have deployed agents running in that environment.

Cron events are system events triggered at scheduled intervals for automated processes.

cron:5-minutes

Triggered every 5 minutes for system maintenance and periodic tasks

{}

{
  environmentId: string
}

cron:hourly

Triggered every hour for scheduled maintenance and cleanup tasks

{}

{
  environmentId: string
}

cron:daily

Triggered once daily for daily maintenance and reporting tasks

{}

{
  environmentId: string
}

cron:weekly

Triggered once weekly for weekly cleanup and archival tasks

{}

{
  environmentId: string
}

​Event Structure

​Listening and Reacting to Events

​Job Events

​job:created

​job:ready

​job:scheduled

​job:updated

​job:completed

​job:outcome-acknowledged

​job:parts-completed

​job:failed

​job:deleted

​Program Events

​program:created

​program:updated

​program:recomputing

​program:recomputed

​File Events

​file:created

​file:updated

​file:deleted

​file:expired

​Record Events

​records:created

​records:updated

​records:deleted

​Sheet Events

​sheet:calculation-updated

​sheet:counts-updated

​sheet:created

​sheet:updated

​sheet:deleted

​Workbook Events

​workbook:created

​workbook:updated

​workbook:deleted

​workbook:expired

​Space Events

​space:created

​space:updated

​space:deleted

​space:expired

​space:archived

​space:guestAdded

​space:guestRemoved

​space:unarchived

​Environment Events

​environment:autobuild-created

​environment:created

​environment:updated

​environment:deleted

​Action Events

​action:created

​action:updated

​action:deleted

​Document Events

​document:created

​document:updated

​document:deleted

​Commit Events

​commit:created

​commit:updated

​commit:completed

​layer:created

​Snapshot Events

​snapshot:created

​Agent Events

​agent:created

​agent:updated

​agent:deleted

​Secret Events

​secret:created

​secret:updated

​secret:deleted

​Data Clip Events

​data-clip:collaborator-updated

​data-clip:created

​data-clip:updated

​data-clip:deleted

​data-clip:resolutions-created

Event Structure

Listening and Reacting to Events

Job Events

job:created

job:ready

job:scheduled

job:updated

job:completed

job:outcome-acknowledged

job:parts-completed

job:failed

job:deleted

Program Events

program:created

program:updated

program:recomputing

program:recomputed

File Events

file:created

file:updated

file:deleted

file:expired

Record Events

records:created

records:updated

records:deleted

Sheet Events

sheet:calculation-updated

sheet:counts-updated

sheet:created

sheet:updated

sheet:deleted

Workbook Events

workbook:created

workbook:updated

workbook:deleted

workbook:expired

Space Events

space:created

space:updated

space:deleted

space:expired

space:archived

space:guestAdded

space:guestRemoved

space:unarchived

Environment Events

environment:autobuild-created

environment:created

environment:updated

environment:deleted

Action Events

action:created

action:updated

action:deleted

Document Events

document:created

document:updated

document:deleted

Commit Events

commit:created

commit:updated

commit:completed

layer:created

Snapshot Events

snapshot:created

Agent Events

agent:created

agent:updated

agent:deleted

Secret Events

secret:created

secret:updated

secret:deleted

Data Clip Events

data-clip:collaborator-updated

data-clip:created

data-clip:updated

data-clip:deleted

data-clip:resolutions-created