Legacy Documentation: This content is maintained for backward compatibility and may not reflect the latest features or best practices. For current documentation, please refer to our updated guides.

The DevXP engineering team hosts office hours every Thursday at 11 a.m. Pacific Time where we answer your questions live and help you get up and running with Flatfile. Join us!

Flatfile is an event-based system. This means that an Event is published on almost any interaction a user has within the Flatfile platform.

A Listener is a function that is triggered by an Event. It’s a powerful building block because it can be completely customized, enabling you to respond to events precisely the way your business and workflow require.

In this step of the tutorial, you’ll learn how to set up a Listener to receive Events.

​
About listeners

Let’s take a look at a basic listener.

export default function (listener) {
  //note: listening to all events with a wildcard can be used while testing but is not 
  //recommended for production, as it will capture all events and may cause performance issues
  listener.on("**", (event) => {
    console.log(`Received event: ${event.topic}`);
  });
}

As you can see, this function is listening on ”**”, which is a wildcard that matches all events on all Apps. All this listener does is log an incoming Event’s topic.

​
Setup your first listener

Let’s walk through setting up your first listener. To do this, you’ll be using some of the tools Flatfile provides for developers.

Flatfile is a Typescript/Javascript platform, so you will need to install Node.js to use all the tools Flatfile provides developers. Though not required, switch to Node.js v18 for the best experience.

First, clone our Getting Started repository.

git clone https://github.com/FlatFilers/getting-started.git

Then, install dependencies.

npm install

Next, add your credentials. To do this, create an .env file at the root of your cloned repository.

cp .env.example .env

Now, update the FLATFILE_API_KEY value, setting it to your Secret Key.

​
Run your first listener

Now that you have listener code configured with credentials, you’re ready to listen for Events.

We’ll run this listener locally by using the “develop” command from the Flatfile CLI.

You may chose to run either a Typescript or a Javascript version of this listener:

npx flatfile@latest develop typescript/index.ts

Congratulations, you have created your first listener!

You should see console output that looks like this:

console
> npx flatfile develop
✔ 1 environment(s) found for these credentials
✔ Environment "development" selected
ncc: Version 0.36.1
ncc: Compiling file index.js into CJS
  ✓ 427ms      GET    200 https://platform.flatfile.com/api/v1/subscription 12345

 File change detected. 🚀
  ✓ Connected to event stream for scope us_env_1234

​
Next steps

To watch your listener receive an event, you’ll need to trigger one. Let’s learn how to leverage your listener to Configure a Space on the fly.