Webhooks

importOK provides several different approaches to import the records once they are ready.

#Record by record

This is by far the simplest approach where the records are passed one by one, in a row. If you already have an API in place, it is recommended to start with this approach. Once you have it working, you can switch to batch processing to improve the performance.

In the following example, a callback is registered for onRecordReady and it will be called one time for each record. Note that the meta object is passed for your convenience.

 1{
 2  fields: {...},
 3  meta: {...},
 4  onRecordReady: async function (record, meta) {
 5    return await fetch('https://your-api.com', {
 6      method: 'POST',
 7      headers: {
 8        'Content-Type': 'application/json'
 9      },
10      body: JSON.stringify(record.getProperties())
11    });
12  }
13}

Every time a callback is completed the progress bar on the user interface will be updated accordingly, demonstrating the progress.

#Batch processing

To improve performance, you can define how many API calls can be executed concurrently. Similar to above scenario, a callback is registered for onRecordReady and it will be called one time for each record but with up to 100 calls in parallel.

 1{
 2  fields: {...},
 3  meta: {...},
 4  throttle: 100,
 5  onRecordReady: async function (record, meta) {
 6    return await fetch('https://your-api.com', {
 7      method: 'POST',
 8      headers: {
 9        'Content-Type': 'application/json'
10      },
11      body: JSON.stringify(record.getProperties())
12    });
13  }
14}

Every time a callback is completed the progress bar on the user interface will be updated accordingly, demonstrating the progress.

#Full set of records

It is also possible to receive the full set which is useful when you want to process the records in the backend.

In the following example, we register a callback for onImportReady and it will be called only once.

 1{
 2  fields: {...},
 3  meta: {...},
 4  onImportReady: async function (records, meta) {
 5    return await fetch('https://your-api.com', {
 6      method: 'POST',
 7      headers: {
 8        'Content-Type': 'application/json'
 9      },
10      body: JSON.stringify(records.getProperties())
11    });
12  }
13}

#Marking records as failed

When a non-successful response status is returned (e.g., 400 Bad Request), the component automatically marks the corresponding records as failed. If you’re sending records individually, only the specific failed record will be marked. For batch or full-set submissions, all failed records in the set will be marked accordingly.

The component displays the failed records and prompts the end-user to download them, helping with troubleshooting and allowing re-upload after the issues are resolved. To include a custom error message for each failed record, use the markAsRejected method. This message will appear as the last column in the downloaded file.

Here’s an example of how to use markAsRejected to mark a record as failed with a custom error message:

 1{
 2  fields: {...},
 3  meta: {...},
 4  onRecordReady: async function (record, meta) {
 5    const response = await fetch('https://your-api.com', {
 6      method: 'POST',
 7      headers: {
 8        'Content-Type': 'application/json'
 9      },
10      body: JSON.stringify(record)
11    });
12 
13    if (!response.ok) {
14      // Mark the record as failed with a custom error message
15      record.markAsRejected(record, 'Custom error message'); 
16    }
17    return response;
18  }
19}

#Meta

The meta object is passed to all callbacks and it contains the following properties:

In addition to the predefined meta data described above, you can also pass your own metadata as part of the available props.