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
}