REST Webhooks 3.0

This guide is for Flatfile Portal 3.0 and Flatfile Workspaces customers. Webhooks are currently in beta; if you would like access to this feature, please reach out to our success team at success@flatfile.io. Please see this guide for information on using Webhooks with Flatfile 2.0. 

What Are REST Webhooks?

REST Webhooks allow you to listen to events in Flatfile and get notified in real time when data is imported and validated by your customers. We use a single subscription URL for our webhooks, which eliminates unnecessary polling and enables faster real-time communication.

To subscribe to an event, click on Team on the left-hand side of your dashboard. On the Team page, click on the Webhook tab.

webhooks tab screenshot

Here, enter the URL where you would like to receive HTTP POST requests. After entering a URL, you can click Send sample payload to URL to validate that your URL is valid and that your end point is receiving payloads. 

Next, use the Subscribed Events drop-down menu to subscribe to a webhook event. 

Portal 3.0 Embeds users can subscribe to the following events:

  • Import submitted

  • Record status modified (record dismissed)

Workspaces users may subscribe to the following events: 

  • New records added

  • Record status modified (record approved, record unapproved, record dismissed)

Additional events are coming soon. If you would like to request an event to be added, please let us know by emailing support@flatfile.com 

Fetching Data from Webhooks

After successfully subscribing to an event, our webhooks will send a payload to your API endpoint whenever that event is triggered. Let’s take a look at a sample payload to see what it contains. 

First, we see the env variable, which can contain identifying user information passed into the payload via the JWT and can also be securely authenticated by signing the env variable with a private key. Next, we have identifying information, including platformEventId, environmentId, teamId, and others. After the identifying information, the payload contains information about the type of event that triggered the webhook. In the above example, we can see that the webhook was triggered by a record status change, indicated by recordStatus. Additional information about what the record status change actually was is stored under rowIds, where we can see which records the status change applies to and that their status has been changed to accepted. The webhook payload does not contain the data that was changed, only the row IDs of the rows where data has been updated.

Depending on the events you subscribe to and your data, the payloads you receive may look a little different, but they should each follow this basic structure. Identifying information first, then specific information about what has changed, such as row IDs and record status.

Below are examples of the different payloads:

Record Approved (Workspaces)

Record Unapproved (Workspaces)

Record Dismissed (Workspaces)