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.

note

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

Example usage

this.importer = new FlatfileImporter(LICENSE_KEY, {
      webhookUrl: "webhook url here",
      fields: [
        {
          label: "Name",
          key: "name",
          description: "Full name",
          validators: [
            {
              validate: "required"
            }
          ]
        },
        {
          label: "Job Title",
          key: "title"
        },
        {
          label: "Email Address",
          key: "email",
          validators: [
            { validate: "unique" }
          ]
        }
      ],
      type: "People",
      allowInvalidSubmit: true,
      managed: true,
      disableManualInput: false
    });

Webhook JSON payload

Parameter	Data type	Description
event.id	String	Uniquely generated webhook event ID
event.type	String	Event type e.g batch.update
event.sequence.count	Integer	Total number of requests to be made for this event
event.sequence.index	Integer	Current request number, starting at 1
data.meta.batch.id	String	Current Batch ID
data.meta.settings.id	Integer	Current Settings ID
data.meta.count	Integer	How 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

{
  "event": {
    "type": "batch:v1:upload",
    "id": "YOUR_UNIQUE_EVENT_ID_WILL_APPEAR_HERE",
    "sequence": {
      "length": 1,
      "index": 0
    }
  },
  "data": {
    "meta": {
      "batch": {
        "id": "YOUR_BATCH_ID_WILL_APPEAR_HERE"
      },
      "settings": {
        "id": null
      },
      "length": 6
    },
    "validRows": [
      {
        "name": "Han Solo",
        "email": "han@millenniumfalcon.com",
        "title": "Captain"
      },
      {
        "name": "Luke Skywalker",
        "email": "luke@therebellion.com",
        "title": "Jedi Knight"
      },
      {
        "name": "Leia Organa",
        "email": "leia@theprincess.com",
        "title": "Leader | Rebel Alliance"
      },
      {
        "name": "Kylo Ren",
        "email": "kylo@firstorder.com",
        "title": "Master of the Knights of Ren"
      },
      {
        "name": "Rey",
        "email": "rey@jakku.com",
        "title": "Scavenger"
      },
      {
        "name": "R2-D2",
        "email": "r2@d2.io",
        "title": "Droid"
      }
    ],
    "invalidRows": []
  }
}