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

​
Description
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.‘
​
Payload
{
  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
}
​
Context
{
  accountId: string
  environmentId: string
  spaceId?: string
  jobId: string
  actorId: string
}

​
job:ready

​
Description
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.
​
Payload
{
  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
}
​
Context
{
  accountId: string
  environmentId: string
  spaceId?: string
  jobId: string
  actorId: string
}
​
Usage Example
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

​
Description
Triggered when a job is scheduled to run at a future time
​
Payload
{
  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
}
​
Context
{
  accountId: string
  environmentId: string
  spaceId?: string
  jobId: string
  actorId: string
}

​
job:updated

​
Description
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.
​
Payload
{
  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
}
​
Context
{
  accountId: string
  environmentId: string
  spaceId?: string
  jobId: string
  actorId: string
}

​
job:completed

​
Description
Triggered when a job has completed successfully
​
Payload
{
  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
}
​
Context
{
  accountId: string
  environmentId: string
  spaceId?: string
  jobId: string
  actorId: string
}

​
job:outcome-acknowledged

​
Description
Triggered to trigger workflow actions after the user has acknowledged that the job has completed or failed. Background jobs will skip this step.
​
Payload
{
  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
}
​
Context
{
  accountId: string
  environmentId: string
  spaceId?: string
  workbookId?: string
  sheetId?: string
  jobId: string
  actorId: string
}

​
job:parts-completed

​
Description
Triggered when all parts of a multi-part job have completed processing
​
Payload
{
  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
  }>
}
​
Context
{
  accountId: string
  environmentId: string
  spaceId?: string
  jobId: string
  actorId: string
}

​
job:failed

​
Description
Triggered when a job fails
​
Payload
{
  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
}
​
Context
{
  accountId: string
  environmentId: string
  spaceId?: string
  workbookId?: string
  sheetId?: string
  jobId: string
  actorId: string
}

​
job:deleted

​
Description
Triggered when a job is deleted
​
Context
{
  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

​
Description
Triggered when a new mapping program is created
​
Payload
{}
​
Context
{
  accountId: string
  environmentId: string
  spaceId: string
  workbookId: string
  sheetId: string
  actorId: string
}

​
program:updated

​
Description
Triggered when a mapping program is updated
​
Payload
{}
​
Context
{
  accountId: string
  environmentId: string
  spaceId: string
  workbookId: string
  sheetId: string
  actorId: string
}

​
program:recomputing

​
Description
Triggered when a mapping program begins recomputing its transformations
​
Payload
{}
​
Context
{
  accountId: string
  environmentId: string
  spaceId: string
  workbookId: string
  sheetId: string
  actorId: string
}

​
program:recomputed

​
Description
Triggered when a mapping program has finished recomputing its transformations
​
Payload
{}
​
Context
{
  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

​
Description
Triggered when a file upload begins or a new file is created
​
Context
{
  accountId: string
  environmentId: string
  spaceId: string
  fileId: string
  actorId: string
}

​
file:updated

​
Description
Triggered when a file is updated. For example, when a file has been extracted into a workbook
​
Context
{
  accountId: string
  environmentId: string
  spaceId: string
  fileId: string
  actorId: string
}
​
Payload
{
  status: string
  workbookId?: string
}

​
file:deleted

​
Description
Triggered when a file is deleted
​
Context
{
  accountId: string
  environmentId: string
  spaceId: string
  fileId: string
  actorId: string
}

​
file:expired

​
Description
Triggered when a file is expired
​
Context
{
  accountId: string
  environmentId: string
  spaceId: string
  fileId: string
}

​
Record Events

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

​
records:created

​
Description
Triggered when new records are added to a sheet
​
Payload
{
  sheetId: string
  recordIds: string[]
  recordCount: number
}
​
Context
{
  environmentId: string
  spaceId: string
  workbookId: string
  sheetId: string
}

​
records:updated

​
Description
Triggered when existing records are modified
​
Payload
{
  sheetId: string
  recordIds: string[]
  changes: Array<{
    recordId: string
    fieldKey: string
    previousValue: any
    newValue: any
  }>
}

​
records:deleted

​
Description
Triggered when records are deleted from a sheet
​
Payload
{
  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

​
Description
Triggered when sheet calculations or formulas are updated
​
Payload
{
  sheetId: string
  workbookId: string  
  calculations: Array<{
    field: string
    formula: string
    updated: boolean
  }>
}
​
Context
{
  accountId: string
  environmentId: string
  spaceId: string
  workbookId: string
  sheetId: string
  actorId: string
}

​
sheet:counts-updated

​
Description
Triggered when record counts for a sheet are updated
​
Payload
{
  sheetId: string
  workbookId: string
  counts: {
    total: number
    valid: number
    error: number
    updated: number
  }
}
​
Context
{
  accountId: string
  environmentId: string
  spaceId: string
  workbookId: string
  sheetId: string
  actorId: string
}

​
sheet:created

​
Description
Triggered when a new sheet is created
​
Payload
{
  sheetId: string
  workbookId: string
  name: string
  slug: string
  fieldCount: number
}

​
sheet:updated

​
Description
Triggered when a sheet Blueprint or configuration is modified
​
Payload
{
  sheetId: string
  workbookId: string
  changes: Array<{
    type: "field_added" | "field_removed" | "field_updated" | "config_updated"
    details: any
  }>
}

​
sheet:deleted

​
Description
Triggered when a sheet is deleted
​
Payload
{
  sheetId: string
  workbookId: string
  name: string
  slug: string
}

​
Workbook Events

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

​
workbook:created

​
Description
Triggered when a new workbook is created
​
Payload
{
  workbookId: string
  spaceId: string
  name: string
  namespace?: string
  sheetCount: number
}

​
workbook:updated

​
Description
Triggered when a workbook is modified
​
Payload
{
  workbookId: string
  spaceId: string
  changes: Array<{
    type: "sheet_added" | "sheet_removed" | "config_updated"
    details: any
  }>
}

​
workbook:deleted

​
Description
Triggered when a workbook is deleted
​
Payload
{
  workbookId: string
  spaceId: string
}

​
workbook:expired

​
Description
Triggered when a workbook expires
​
Payload
{
  workbookId: string
  spaceId: string
}

​
Space Events

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

​
space:created

​
Description
Triggered when a new project (space) is created
​
Payload
{
  spaceId: string
  environmentId: string
  name: string
  appId?: string
}

​
space:updated

​
Description
Triggered when a project is modified
​
Payload
{
  spaceId: string
  environmentId: string
  changes: Array<{
    field: string
    previousValue: any
    newValue: any
  }>
}

​
space:deleted

​
Description
Triggered when a space is deleted
​
Context
{
  accountId: string
  environmentId: string
  spaceId: string
  workbookId: string
  actorId: string
}

​
space:expired

​
Description
Triggered when a space is expired
​
Context
{
  accountId: string
  environmentId: string
  spaceId: string
  workbookId: string
}

​
space:archived

​
Description
Triggered when a space is archived
​
Context
{
  accountId: string
  environmentId: string
  spaceId: string
}

​
space:guestAdded

​
Description
Triggered when a guest is added
​
Context
{
  actorId: string
  accountId: string
  environmentId: string
  spaceId: string
}

​
space:guestRemoved

​
Description
Triggered when a guest’s access is revoked from a space
​
Context
{
  actorId: string
  accountId: string
  environmentId: string
  spaceId: string
}

​
space:unarchived

​
Description
Triggered when a space is unarchived and restored to active status
​
Payload
{}
​
Context
{
  actorId: string
  accountId: string
  environmentId: string
  spaceId: string
}

​
Environment Events

Environment events are triggered for organization-level changes.

​
environment:autobuild-created

​
Description
Triggered when an autobuild configuration is created for an environment
​
Payload
{}
​
Context
{
  environmentId: string
  accountId: string
  appId?: string
  actorId: string
}

​
environment:created

​
Description
Triggered when a new environment is created
​
Payload
{
  environmentId: string
  name: string
  slug: string
  isProd: boolean
}

​
environment:updated

​
Description
Triggered when an environment is modified
​
Payload
{
  environmentId: string
  changes: Array<{
    field: string
    previousValue: any
    newValue: any
  }>
}

​
environment:deleted

​
Description
Triggered when an environment is deleted
​
Payload
{
  environmentId: string
  deletedAt: string
  deletedBy: string
}

​
Action Events

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

​
action:created

​
Description
Triggered when a new custom action is created
​
Payload
{
  actionId: string
  name: string
  label: string
  description?: string
  type: string
}
​
Context
{
  accountId: string
  environmentId: string
  spaceId: string
  workbookId?: string
  sheetId?: string
  actorId: string
}

​
action:updated

​
Description
Triggered when a custom action is updated
​
Payload
{
  actionId: string
  name: string
  label: string
  description?: string
  type: string
  changes: Array<{
    field: string
    previousValue: any
    newValue: any
  }>
}
​
Context
{
  accountId: string
  environmentId: string
  spaceId: string
  workbookId?: string
  sheetId?: string
  actorId: string
}

​
action:deleted

​
Description
Triggered when a custom action is deleted
​
Payload
{
  actionId: string
  name: string
}
​
Context
{
  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

​
Description
Triggered when a document is created on a workbook
​
Context
{
  actorId: string
  spaceId: string
  accountId: string
  documentId: string
  environmentId: string
}

​
document:updated

​
Description
Triggered when a document is updated on a workbook
​
Context
{
  actorId: string
  spaceId: string
  accountId: string
  documentId: string
  environmentId: string
}

​
document:deleted

​
Description
Triggered when a document is deleted on a workbook
​
Context
{
  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

​
Description
Triggered when a cell in a record is created or updated
​
Payload
{
  sheetId: string
  workbookId: string
  versionId: string
  sheetSlug: string
}

​
commit:updated

​
Description
Triggered when commit metadata or details are updated
​
Payload
{
  sheetId: string
  workbookId: string
  commitId: string
  versionId: string
  changes: Array<{
    field: string
    previousValue: any
    newValue: any
  }>
}
​
Context
{
  accountId: string
  environmentId: string
  spaceId: string
  workbookId: string
  sheetId: string
  actorId: string
}

​
commit:completed

​
Description
Triggered when a commit has completed (only when trackChanges is enabled)
​
Payload
{
  sheetId: string
  workbookId: string
  versionId: string
  commitId: string
}

​
layer:created

​
Description
Triggered when a new layer is created within a commit
​
Payload
{
  sheetId: string
  workbookId: string
  layerId: string
  commitId: string
}

​
Snapshot Events

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

​
snapshot:created

​
Description
Triggered when a snapshot is created of a sheet
​
Payload
{
  snapshotId: string
  sheetId: string
  workbookId: string
  spaceId: string
}

​
Agent Events

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

​
agent:created

​
Description
Triggered when a new agent is deployed
​
Payload
{
  agentId: string
  environmentId: string
}

​
agent:updated

​
Description
Triggered when an agent is updated
​
Payload
{
  agentId: string
  environmentId: string
}

​
agent:deleted

​
Description
Triggered when an agent is deleted
​
Payload
{
  agentId: string
  environmentId: string
}

​
Secret Events

Secret events are triggered when secrets are managed.

​
secret:created

​
Description
Triggered when a new secret is created
​
Payload
{
  secretId: string
  spaceId: string
  environmentId: string
}

​
secret:updated

​
Description
Triggered when a secret is updated
​
Payload
{
  secretId: string
  spaceId: string
  environmentId: string
}

​
secret:deleted

​
Description
Triggered when a secret is deleted
​
Payload
{
  secretId: string
  spaceId: string
  environmentId: string
}

​
Data Clip Events

Data clip events are triggered when data clips are managed.

​
data-clip:collaborator-updated

​
Description
Triggered when collaborators are added or removed from a data clip
​
Payload
{
  dataClipId: string
  collaborators: string[]
  changes: Array<{
    action: "added" | "removed"
    userId: string
  }>
}
​
Context
{
  accountId: string
  environmentId: string
  spaceId: string
  dataClipId: string
}

​
data-clip:created

​
Description
Triggered when a new data clip is created
​
Payload
{
  dataClipId: string
  accountId: string
  status: string
}

​
data-clip:updated

​
Description
Triggered when a data clip’s details are updated
​
Payload
{
  dataClipId: string
  accountId: string
  status: string
}

​
data-clip:deleted

​
Description
Triggered when a data clip is deleted
​
Payload
{
  dataClipId: string
  accountId: string
  status: string
}

​
data-clip:resolutions-created

​
Description
Triggered when new conflict resolutions are created for a data clip
​
Payload
{
  dataClipId: string
  resolutions: Array<{
    conflictId: string
    resolution: any
    resolvedBy: string
  }>
}
​
Context
{
  accountId: string
  environmentId: string
  spaceId: string
  dataClipId: string
}

​
data-clip:resolutions-refreshed

​
Description
Triggered when conflict resolutions are refreshed or recalculated for a data clip
​
Payload
{}
​
Context
{
  accountId: string
  environmentId: string
  spaceId: string
  dataClipId: string
}

​
data-clip:resolutions-updated

​
Description
Triggered when existing conflict resolutions are updated for a data clip
​
Payload
{
  dataClipId: string
  resolutions: Array<{
    conflictId: string
    resolution: any
    resolvedBy: string
    updatedAt: string
  }>
  changes: Array<{
    conflictId: string
    previousResolution: any
    newResolution: any
  }>
}
​
Context
{
  accountId: string
  environmentId: string
  spaceId: string
  dataClipId: string
}

​
Canvas Events

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

​
canvas:created

​
Description
Triggered when a new canvas is created
​
Payload
{
  // Full canvas object with all properties
}
​
Context
{
  canvasId: string
  spaceId: string
  environmentId: string
  accountId: string
}

​
canvas:updated

​
Description
Triggered when a canvas is updated
​
Payload
{
  // Full canvas object with all properties
}
​
Context
{
  canvasId: string
  spaceId: string
  environmentId: string
  accountId: string
}

​
canvas:deleted

​
Description
Triggered when a canvas is deleted
​
Payload
{
  // Full canvas object with all properties
}
​
Context
{
  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

​
Description
Triggered when a new canvas area is created
​
Payload
{
  // Full canvas area object with all properties
}
​
Context
{
  canvasAreaId: string
  canvasId: string
}

​
canvas-area:updated

​
Description
Triggered when a canvas area is updated
​
Payload
{
  // Full canvas area object with all properties
}
​
Context
{
  canvasAreaId: string
  canvasId: string
}

​
canvas-area:deleted

​
Description
Triggered when a canvas area is deleted
​
Payload
{
  // Full canvas area object with all properties
}
​
Context
{
  canvasAreaId: string
  canvasId: string
}

​
Thread Events

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

​
thread:created

​
Description
Triggered when a new AI conversation thread is created
​
Payload
{
  threadId: string
  title?: string
  status: string
  createdAt: string
}
​
Context
{
  accountId: string
  environmentId: string
  spaceId: string
  threadId: string
  actorId: string
}

​
thread:updated

​
Description
Triggered when an AI conversation thread is updated
​
Payload
{
  threadId: string
  title?: string
  status: string
  changes: Array<{
    field: string
    previousValue: any
    newValue: any
  }>
}
​
Context
{
  accountId: string
  environmentId: string
  spaceId: string
  threadId: string
  actorId: string
}

​
thread:deleted

​
Description
Triggered when an AI conversation thread is deleted
​
Payload
{}
​
Context
{
  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

​
Description
Triggered every 5 minutes for system maintenance and periodic tasks
​
Payload
{}
​
Context
{
  environmentId: string
}

​
cron:hourly

​
Description
Triggered every hour for scheduled maintenance and cleanup tasks
​
Payload
{}
​
Context
{
  environmentId: string
}

​
cron:daily

​
Description
Triggered once daily for daily maintenance and reporting tasks
​
Payload
{}
​
Context
{
  environmentId: string
}

​
cron:weekly

​
Description
Triggered once weekly for weekly cleanup and archival tasks
​
Payload
{}
​
Context
{
  environmentId: string
}