Setting Up Your First Listener
Listeners are the core of Flatfile’s event-driven architecture. They respond to events throughout the data import lifecycle, from space configuration to data validation and job processing. This guide will help you understand how to create and organize listeners effectively.
If you aren’t interested in a code-forward approach, we recommend starting with AutoBuild, which uses AI to analyze your template or documentation and then automatically creates and deploys a Blueprint (for schema definition) and a Listener (for validations and transformations) to your Flatfile App.
Once you’ve started with AutoBuild, you can always download your Listener code and continue building with code from there!
About Listeners
Listeners handle different types of events in Flatfile:
- Space Configuration: Setting up workbooks, sheets, and themes
- Data Validation: Custom field and record-level validation
- Job Processing: Handling long-running operations
- File Operations: Processing uploaded files
- User Interactions: Responding to custom actions
For a thorough explanation of listeners and how they fit into the Flatfile ecosystem, see Events and Listeners.
Install Dependencies
Install the required packages for building Flatfile listeners:
Create Your Listener File
Create a new file called listener.js
(or listener.ts
for TypeScript):
Testing and Deployment
For complete testing and deployment documentation, see the CLI Reference.
Authentication Setup
For complete authentication setup examples, see the Authentication Examples guide.
Local Development
To test your listener locally, you can use the flatfile develop
command. This will start a local server that will listen for events and respond to them, and will also watch for changes to your listener code and automatically reload the server.
Deploy to Flatfile Cloud
Deploying your listener will create a new Agent in your Flatfile environment. Under the hood, this will compile all of your listener code and its dependencies into a single file, which it sends to the Flatfile API’s POST /v1/agents
endpoint.
That’s it! Your listener will:
- Create a workbook when a space is opened
- Process data when users click Submit
- Handle the complete data import workflow
What Just Happened?
Your minimal listener handles two key events:
space:configure
- Sets up the data structure (workbook + sheets)job:ready
- Processes data when users submit
For a more detailed explanation and examples of how to add a custom action, see the Actions guide.
Sheet Validation Example
This example uses a commit:created
event listener to detect duplicate (+) email addresses. Records with duplicate emails receive a Warning, while records with emails that appear 3+ times receive an Error.
Because this example checks for duplicates across all records, it needs to retrieve every record from the sheet. The vast majority of validations, however, only need to work with individual records after they’ve been changed – for example, validating the format of an email addresses or ensuring that a date is in the past.
For those scenarios, we recommend using the Record Hook plugin, which provides a faster, cleaner, and more object-oriented approach to validation.
If you use both Record Hooks and regular listener validators (like this one) on the same sheet, you may encounter race conditions. Record Hooks will clear all existing messages before applying new ones, which can interfere with any messages set elsewhere. We have ways to work around this, but it’s a good idea to avoid using both at the same time.