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;
}
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.‘
{
job: string // domain:operation format (e.g., "space:configure")
info?: string
domain: string // event domain (e.g., "space")
status: "created"
operation: string // operation name (e.g., "configure")
}
{
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.
{
job: string // domain:operation format (e.g., "space:configure")
info?: string
domain: string // event domain (e.g., "space")
status: "ready"
operation: string // operation name (e.g., "configure")
}
{
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: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.
{
job: string // domain:operation format (e.g., "space:configure")
info?: string
domain: string // event domain (e.g., "space")
status: string
operation: string // operation name (e.g., "configure")
}
{
accountId: string
environmentId: string
spaceId?: string
jobId: string
actorId: string
}
job:completed
Triggered when a job has completed successfully
{
job: string // domain:operation format (e.g., "space:configure")
info?: string
domain: string // event domain (e.g., "space")
status: "complete"
operation: string // operation name (e.g., "configure")
}
{
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.
{
job: string // domain:operation format (e.g., "sheet:buildSheet")
info?: string
domain: string // event domain (e.g., "sheet")
status: string // e.g., "failed"
operation: string // operation name (e.g., "buildSheet")
}
{
accountId: string
environmentId: string
spaceId?: string
workbookId?: string
sheetId?: string
jobId: string
actorId: string
}
job:failed
Triggered when a job fails
{
job: string // domain:operation format (e.g., "sheet:buildSheet")
info?: string
domain: string // event domain (e.g., "sheet")
status: "failed"
operation: string // operation name (e.g., "buildSheet")
}
{
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
}
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.
record:created
Triggered when new records are added to a sheet
{
sheetId: string
recordIds: string[]
recordCount: number
}
{
environmentId: string
spaceId: string
workbookId: string
sheetId: string
}
record:updated
Triggered when existing records are modified
{
sheetId: string
recordIds: string[]
changes: Array<{
recordId: string
fieldKey: string
previousValue: any
newValue: any
}>
}
record: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: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:records:created
Triggered when new records are added to a sheet (alias for record:created)
sheet:deleted
Triggered when a sheet is deleted
{
sheetId: string
workbookId: string
name: string
slug: string
}
sheet:records:updated
Triggered when records in a sheet are modified (alias for record:updated)
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
}
App Events
App events are triggered when applications are created, updated, or deployed.
app:created
Triggered when a new app is created
{
appId: string
environmentId: string
name: string
slug: string
}
app:updated
Triggered when an app configuration is modified
{
appId: string
environmentId: string
changes: Array<{
type: "config_updated" | "listener_updated" | "metadata_updated"
details: any
}>
}
app:deployed
Triggered when an app is deployed to production
{
appId: string
environmentId: string
production: boolean
deployedAt: string
}
Environment Events
Environment events are triggered for organization-level changes.
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
}
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: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: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
}
