Setup a listener

You’ve just created a Workbook.

In Flatfile, an event-based system, that means an Event was published.

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 requires.

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) {
  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. 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.

First, clone our Getting Started repository.

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

Then, install dependencies.

npm install

Next, add your credentials.

Remember the secrets key you used to create your first Workbook? Your listener is going to use that same credential to receive Events.

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 secrets key.

Each secrets key is scoped to an environment, so you will also need to update the FLATFILE_ENVIRONMENT_ID value to the one found on the same page as your secrets 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 by changing into the appropriate directory. Then, run the following command:

npx flatfile@latest develop

Congratulations, you have created your first listener!

You should see console output that looks like this:

> 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

​

Watch your Events

To watch your listener receive an event, you’ll need to trigger one.

Go to your Flatfile Workbook and make a few changes. For example, try typing text into a cell.

Typing in a cell (editing a Record) triggers an Event! And because your listener was running, it logged your activity.

 ▶ commit:created  10:13:05.159 AM us_evt_1234
 ↳ on(**, {})
 ↳ on(commit:created, {"sheetSlug":"contacts"})

​

Next steps

Now that you’ve created a listener, a powerful building block on the Flatfile platform, let’s learn how to leverage your listener to Transform and validate data.