Webhooks Implementation Guide

About Flatfile Webhooks

Flatfile Webhooks allow you to subscribe to events that are happening in your Flatfile account. Rather than requiring you to pull information via our API, Flatfile can send an HTTP POST request, with a JSON body, to the endpoint that you configure when you setup your data model.

In this guide, we'll get you started with a basic webhook configuration to subscribe to new imports. The imports will be submitted using HTTP POST to the webhook URL specified in your Flatfile data model.

Webhook configuration

You can add a webhook url in your flatfile dashboard via Data models. Go to Data Models -> Add new data model or create one from csv -> Add webhook endpoint url.

Here's what the data model looks like:


Data ModelThe name of your data model.
FieldsYour dataset column names.
Webhook URLA webhook URL is the HTTP endpoint where upload events are send. This URL must be valid, publicly accessible, and able to accept POST requests. We consider any HTTP status codes between 200 and 299 as successful. All other codes are considered an error and will show up in the Flatfile webhook log as a failure.

Webhook format

Below is a sample JSON webhook request body that your application will need to accept to use Flatfile webhooks. Currently, only one event type is supported: "batch.upload"
For testing purposes, you could use RequestBin, Webhook Site or ngrok.

"event": {
"type": "batch.upload",
"id": "0bce4ec0-7058-4e71-a5a4-78b4155edd2f",
"sequence": {
"count": 1,
"index": 1
"data": {
"meta": {
"batch": {
"id": "596c2c5f-2884-4444-9ccb-2f0772877508"
"schema": {
"id": 8
"count": 4
"validRows": [
"name": "Rack 9823",
"color": "black",
"nick": "Snarlz",
"helmet": "triangle"
"name": "10 Paws",
"color": "fuschia",
"nick": "MAXX",
"helmet": "hexagonal"
"invalidRows": []

In the next section, we'll explain each field in the request body.

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.schema.idIntegerCurrent Schema 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