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

Usage

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.

Example usage

Webhook JSON payload

ParameterData typeDescription
event.id
StringUniquely generated webhook event ID
event.type
StringEvent type e.g batch.update
event.sequence.count
IntegerTotal number of requests to be made for this event
event.sequence.index
IntegerCurrent request number, starting at 1
data.meta.batch.id
StringCurrent Batch ID
data.meta.schema.id
IntegerCurrent Schema ID
data.meta.count
IntegerHow many records in the request, currently this is not configurable and is set at 1,000 records per request maximum
data.validRows
Object[]Array of row data objects that passed validation
data.invalidRows
Object[]Array of row data objects that failed validation

Example JSON POST