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

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

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.

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
}

Getting Started

Core Concepts

Coding Tutorial

Plugins

Advanced Guides

Embedding Flatfile

Reference

​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

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