Webhook

Integrate with our webhook to receive imported data into your backend.

tip

Many users prefer to use the onData browser callback instead of webhooks.

Integration

• First, set your Importer's Webhook URL in the UseCSV admin. UseCSV will make a POST request with a JSON body containing the imported data and some other useful details.

Note: If you want to receive webhook requests to your locally running app, you can use cloudflared to create a free tunnel.

When a client uploads a csv file using your Importer in the frontend, UseCSV will send the csv rows to the Webhook URL in batches of 1,000 rows by default if batchSize is not used. Each batch request will wait for a response from your backend before sending the next batch request. We do this to allow you to process the import in your backend as part of the webhook request, without the need to manage your own processing queuing system.

Webhook request format

POST <Webhook URL (set in Importer)>
HEADERS
body:
{
  "uploadId": 231, 
  "fileName": "data.csv",
  "importerId": "35a01b40-31f5-4d35-9f79-b844d5b1a423",
  "matchedColumnsMap": { 
    "firstName": "first name", 
    "email": "email address"
  },
  "uploadedFileHeaders": ["first name", "email address", "age"],
  "batch": {
    "index": 1,
    "count": 2,
    "totalRows": 2000
  },
  "user": { userId: "12345" },
  "metadata": { anotherId: "1" },
  "rows": [
    {
      "row": 1, // row number
      "firstName": "Mari",
      "email": "mari@gmail.com",
    },
    {
      "row": 2, // row number
      "firstName": "John",
      "email": "john@gmail.com",
    },
  ],
}

body parameters

• uploadId: upload ID.
• importerId: importer ID.
• fileName: uploaded file name.
• user json object of user object if provided.
• metadatajson object of metadata object if provided.
• matchedColumnsMap: json object of matched columns with keys of configured columns and column names in the original user uploaded file.
• uploadedFileHeaders: array of strings of uploaded file headers (column names) including matched, un-matched and skipped headers.
• rows: array of json objects of rows, with keys of:
  • row: number of row in the uploaded file starting from 1.
  • columnName: cell value.
• batch: json object of batch details, with keys of:
  • index: number of batch starting from 1.
  • count: number of total batches expected to be received.
  • totalRows: number of total rows per file.

Your webhook server must respond to receive the next batch. There is a 10 minutes request timeout, which gives you ample time to process the batch before responding.

Respond with a 200 status to continue and receive the next batch. Responding with any other status code will halt further webhook requests for the batch.

If specific rows cannot be imported, and you want to let the user know, you can include an errors JSON array in the body of your 200 response:

status: 200
body: {
  errors: [
    {
      row: 1, // row number
      msg: "this row is invalid"
    }
  ]
}

The user will be able to download a csv file of failed rows with these errors included in an error column.

Security

The UseCSV Importer modal and webhooks are secure and encrypted. For added security, please follow the recommended below:

Validate uploads

When a user uploads a file using the Importer plugin in your app, you may want to validate who made the upload. This can be done by including one or more attributes in the frontend Importer user and/or metadata props. For example you can include a userId attribute in the user prop, which you can verify in your backend when a webhook is received.