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
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
}