This article is for Flatfile's Portal 3.0 and Workspaces. If you'd like to check out the latest version of the Flatfile Data Exchange Platform, click here!

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.

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.

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 users can subscribe to the following events:

Workspaces users may subscribe to the following events:

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.

Please note: If you are setting a userId for an import via your JWT, that will not be the same UserId that is returned in the Webhook payload. The Webhook payload will display a UUID assigned to each unique user by Flatfile.

Below are examples of the different payloads: