Skip to main content

Webhook

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

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.
tip

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 // ID of the uploaded file
"fileName": "data.csv" // Uploaded file name
"importerId": "35a01b40-31f5-4d35-9f79-b844d5b1a423" // ID of the Importer
"batch": {
"index": 1 // which batch number this request is (starts at 1)
"count": 2 // total number of batches to be sent
"totalRows": 2000 // total rows in all batches in this import
}
"user": {
"userId":1 // JSON data provided by you through the plugin
},
"metadata": {...}, // JSON data provided by you through the plugin
"rows": [
{
"row": 1,
"firstname": "john",
"lastname : "adams"
},
......
]
}

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.