Configure a submit action

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!

Actions refer to buttons added to the user interface that trigger Jobs within the Flatfile platform when clicked by users. They enable you to run complex operations and streamline workflows. They are declared as part of the Blueprint that defines a Workbook.

Adding your first Action

In this example, we’re going to add behavior to our Workbook’s primary Action (submitAction). When the button is clicked by a user, our code will call out to an external webhook receiver provided by the webhook.site service.

  1. To create the receiver, navigate to webhook.site
  2. Copy the value of the path after webhook.site for Your unique URL.
  3. Next, add the following to your default export function.
import api from '@flatfile/api'

export default function(listener) {
  // existing code

  listener.filter({ job: 'workbook:submitAction' }, (configure) => {
    configure.on('job:ready', async (event) => {
      const { jobId, workbookId } = event.context

      //get all sheets
      const sheets = await api.sheets.list({ workbookId })

      const records = {};
      for (const [index, element] of sheets.data.entries()) {
        records[`Sheet[${index}]`] = await api.records.get(element.id);

      try {
        await api.jobs.ack(jobId, {
          info: 'Starting job to submit action to webhook.site',
          progress: 10,

        const webhookReceiver =
          process.env.WEBHOOK_SITE_URL ||

        const response = await axios.post(
            method: 'axios',
            headers: {
              'Content-Type': 'application/json',

        if (response.status === 200) {
          await api.jobs.complete(jobId, {
            outcome: {
                'Data was successfully submitted to webhook.site. Go check it out!',
        } else {
          throw new Error('Failed to submit data to webhook.site')
      } catch (error) {
        console.log(`webhook.site[error]: ${JSON.stringify(error, null, 2)}`)

        await api.jobs.fail(jobId, {
          outcome: {
              "This job failed probably because it couldn't find the webhook.site URL.",

Testing your Action

  1. With the develop command still running in terminal, head to your Workbook and click the submit Action in the top right corner.
  2. In webhook.site, look at the query log and observe that the webhook received a call; this is the Action running.

Recap & Next Steps

Congratulations! You now have a Workbook with transformations, validations, and a submit Action to get the data out.

To this point, we’ve been running our listener code locally using the develop command. Next, you should deploy your code.