Flatfile and webhooks

Flatfile's webhooks give you the freedom to subscribe to events that happen with your imports as opposed to having to pull the information via our API. With webhooks, you will specify a webhookUrl in your config, and when there is a completed file upload, we will send an HTTP POST request with the data to the specified URL.

When should I use Webhooks?

This is one of our optional configurations and can simply be ignored if this doesn't interest you or meet your needs. You might want to look into this feature if:

  • You don't want to handle submitting data within the Frontend configuration
  • You want to grab the results and also handle the results in a different way on the frontend of your application
  • You want to allow your users to quickly close out of imports and still get the data behind the scenes


To use webhooks, use the optional webhookUrl as an object key within the FlatfileImporter() method. In the example below, you'll see that this should go at the same level as fields, and will look like webhookUrl: "https://your-data.com/endpoint" . For testing purposes, you can use something like webhook.site to get a test endpoint to play around with how this works.

In order for the webhookUrl setting to work properly, you must also set the managed setting to true.

Example usage

Webhook JSON payload

ParameterData typeDescription
event.idStringUniquely generated webhook event ID
event.typeStringEvent type e.g batch.update
event.sequence.countIntegerTotal number of requests to be made for this event
event.sequence.indexIntegerCurrent request number, starting at 1
data.meta.batch.idStringCurrent Batch ID
data.meta.settings.idIntegerCurrent Settings ID
data.meta.countIntegerHow many records in the request, currently this is not configurable and is set at 1,000 records per request maximum
data.validRowsObject[]Array of row data objects that passed validation
data.invalidRowsObject[]Array of row data objects that failed validation