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. 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
WEBHOOK_SECRET: <Webhook Secret (find it in API Keys section of UseCSV admin)>
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 recommendations below:

Verify webhook requests

Webhook requests include a WEBHOOK_SECRET header which can be used to verify that the request has come from UseCSV. Find the WEBHOOK_SECRET value in the API Keys admin section, and when you receive a webhook request, check the WEBHOOK_SECRET header matches this value. Reject requests that don't match the value or don't include the WEBHOOK_SECRET header.

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.