Webhooks: Use-Cases and Applications

Overview:

Webhooks are POST requests made to an endpoint each time a certain task is completed, using the result of the task as the payload. They are divided into topics and job types. Currently, supported topics and job types are:

Order created
Job complete
- Composite
- Export
- Import
- Render Vray
- Render Webgl

For the Job complete topic you can also further specify one or more completion status. That can be useful for handling things differently whether a job has failed or succeeded.

On the following sections we will focus on specific use cases for certain webhooks and their implementation.

Post-processing imported assets

Webhook: Topic - Job complete | Type: Import | Status: Success

One common automation requirement of projects is to do some type of post processing to imported assets based on the asset type and some sort of naming convention. Because the file name can be controlled by the user before uploading the file to the platform, we can take advantage of it.

Let’s look at an example of adding tags and metadata to assets after they are uploaded to the platform. The first step would be to subscribe to the topic and point it to the url of where you will host your endpoint.

If you want to use your local server to develop, you might need to use port forwarding to allow posting to your external ip address. Here is an article describing how to accomplish that on linux.

After you subscribe, the next step is to get your server up. In this example we will use a simple node server:

const express = require('express');
const cors = require('cors');
const port = process.env.PORT || 8080;
const axios = require('axios');
const handler = require('./handler');
const app = express();
app.use(express.json());
app.use(cors());
const apiPath = 'https://preview.threekit.com/api/';
const getFile = (fileId) => {
 return axios({
   method: 'get',
   url: `${apiPath}files/${fileId}/content`,
 });
};

app.post('/import', async (req, res) => {
 try {
   const filedId = req.body.data?.tasks[0]?.runs[0]?.results?.files[0]?.id;
   if (filedId) {
     // Fetch the results json
     const resultObj = await getFile(filedId).then((content) => content.data);
     // Perform some post processing of assets
     await handler(resultObj);
     res.send(200);
   } else res.send(400);
 } catch (error) {
   console.log(error);
   res.status(500).send(error);
 }
});

app.listen(port, () => console.log(`App listening on port ${port}`));

Here is an example of a payload for a successful import job:

{
  "topic": "jobs",
  "action": "updated",
  "data": {
    "id": "785d7e7c-2958-43c6-8658-7653c3015420",
    "createdBy": "bed6e3c9-e781-42ac-a676-90b0e5ab4c33",
    "orgId": "bed6e3c9-e781-42ac-a676-90b0e5ab4c33",
    "title": "Import",
    "schedulerState": "active",
    "type": "import",
    "createdAt": "2020-05-22T16:24:26.265Z",
    "updatedAt": "2020-05-22T16:24:26.277Z",
    "parameters": {},
    "taskStatusPending": 1,
    "taskStatusRunning": 0,
    "taskStatusStopped": 0,
    "status": "success",
    "taskProgress": 0,
    "taskCount": 1,
    "taskResultSuccesses": 0,
    "taskResultFailures": 0,
    "priority": 0,
    "tasks": [
      {
        "id": "03160180-db96-40bd-ab84-d200d6728596",
        "createdBy": "bed6e3c9-e781-42ac-a676-90b0e5ab4c33",
        "title": "Import",
        "type": "import",
        "createdAt": "2020-05-22T16:24:26.271Z",
        "parameters": { "fileId": "63ef52d4-3753-4097-b110-3ba5250f33ad" },
        "orgId": "bed6e3c9-e781-42ac-a676-90b0e5ab4c33",
        "jobId": "785d7e7c-2958-43c6-8658-7653c3015420",
        "reportProgress": true,
        "updatedAt": "2020-05-22T16:24:49.992Z",
        "runStatus": "stopped",
        "runResult": "Success",
        "runProgress": 1,
        "runs": [
          {
            "id": "a499da29-e862-40dc-97d9-679b976aae93",
            "taskId": "03160180-db96-40bd-ab84-d200d6728596",
            "createdAt": "2020-05-22T16:24:29.350Z",
            "updatedAt": "2020-05-22T16:24:49.987Z",
            "stoppedAt": "2020-05-22T16:24:49.972Z",
            "results": {
              "files": [
                {
                  "id": "fa79c338-3186-4bc8-a9b2-090e44502fd9",
                  "name": "result.json"
                }
              ],
              "stderr": {
                "id": "b60b5d35-1f45-43af-b83c-7fa5c986c73f",
                "name": "stderr"
              },
              "stdout": {
                "id": "dd474cd9-4047-4a02-bed4-4c05dbbd89b6",
                "name": "stdout"
              }
            },
            "resultCode": "Success",
            "resultMessage": null,
            "error": null,
            "progress": 1,
            "machine": null,
            "startedAt": "2020-05-22T16:24:29.339Z",
            "GPUTime": null,
            "CPUTime": null,
            "jobId": "785d7e7c-2958-43c6-8658-7653c3015420",
            "reportProgress": true,
            "orgId": "bed6e3c9-e781-42ac-a676-90b0e5ab4c33",
            "createdBy": "bed6e3c9-e781-42ac-a676-90b0e5ab4c33",
            "RAMUsage": null,
            "wallClockTime": null,
            "requestCPUs": 1,
            "limitCPUs": null,
            "nodeCPUs": 8,
            "requestRAM": "11811160064",
            "limitRAM": "11811160064",
            "nodeRAM": "31615754240",
            "cpuPlatform": "Intel Broadwell",
            "machineType": "n1-standard-8",
            "gpuType": null,
            "instanceID": "1435505946538957800",
            "zone": "us-east4-b",
            "preemptible": true,
            "podId": "b43efff6-9c48-11ea-ab79-42010a960075"
          }
        ]
      }
    ]
  },
  "webhook": "494add29-dfdd-4243-b96b-e6a7602a0212"
}

From that, we are interested in the result.json file for the only task/run that was executed by this job which we are fetching using the getFile function. Here are some example of of what that response content looks like:

Textures:

{
 "scene": [],
 "model": [],
 "material": [],
 "texture": [
   {
     "assetId": "d0d0c9ac-f787-44b5-b1c4-601d7d7b702d",
     "name": "2301_anisotropyRot"
   },
   {
     "assetId": "8be59ea2-d500-4e87-b703-391649e2c338",
     "name": "2301_anisotropy"
   },
   {
     "assetId": "19c2b748-38cd-4b27-a82f-2358795cef53",
     "name": "2301_glossiness"
   },
   {
     "assetId": "63f526a8-f6fc-4434-999f-1a772196a4e9",
     "name": "2301_specular"
   },
   {
     "assetId": "2075be20-b7f5-4da5-aab5-0f971a1bbf7a",
     "name": "2301_normal"
   },
   {
     "assetId": "ed15ccb1-6a63-4c15-b102-095742c7cacd",
     "name": "2301_diffuse"
   }
 ],
 "upload": []
}

Model:

{
 "scene": [],
 "model": [
{
     "assetId": "d0d0c9ac-f787-44b5-b1c4-601d7d7b702d",
     "name": "ClassicJacket_JacketLapel_Nocth_JacketFront_2Button"
   }
],
 "material": [],
 "texture": [],
 "upload": []
}

After we get the results object we pass it to our handler function which will perform some post processing of assets which will rely on the asset name and type.

Common use cases for this are:

Adding metadata to the asset, so it can be fetched by a metadata query action.
Triggering renders after textures are updated.
Modifying the review tags on catalog items that use these assets.

Here is an example of implementation:

const getAssetList = require('../task/getAssetList');
const updateAsset = require('../task/updateAsset');
const deleteAssets = require('../task/deleteAssets');
const renderAsset = require('../task/renderConfigurationLayer');

const textureRegex = /^[0-9]{3,4}_.+/;
const modelRegex = /^(Classic|Modern|Tuxedo).+_.+/;

const RENDER_ASSETS = {
 SUIT: {
   stageId: '',
   assetId: '',
   width: 2500,
 },
 SWATCH: {
   stageId: '',
   assetId: '',
   width: 1500,
 },
};

const orgId = '';
const authToken = '';

const handler = async (result) => {
 if (
   result.texture &&
   result.texture.length > 0 &&
   textureRegex.test(resultObj.texture[0].name)
 ) {
   // Handle texture updates
   await updateTextures(result);
 }
 if (
   result.model &&
   result.model.length > 0 &&
   modelRegex.test(resultObj.model[0].name)
 ) {
   // Handle model updates
   await updateModels(result);
 }
};

const updateModels = async (resultObj) => {
 // Internal function to assing metadata
 const assignMetadata = (name, value) => ({
   type: 'String',
   name,
   values: [],
   defaultValue: value,
 });
 // Build indexed list of models
 const ids = resultObj.model.reduce((acc, item) => {
   acc[item.assetId] = item;
   return acc;
 }, {});
 // Get all models from the asset library and find only the matching models to update
 const models = await getAssetList(orgId, authToken, { type: 'model' });
 const matchingModels = models.filter((model) => ids[model.product.id]);
 // Assign metadata and tags based on naming convention
 matchingModels.forEach((model) => {
   const splitName = model.product.name.split('_');
   if (splitName.length % 2 === 1 || splitName.length === 2) {
     model.product.tags = [splitName[0], splitName[1]];
     const newMeta = [
       assignMetadata('Product', splitName[0]),
       assignMetadata('Item', splitName[1]),
     ];
     for (let i = 1; i < splitName.length - 1; i += 2) {
       newMeta.push(assignMetadata(splitName[i], splitName[i + 1]));
     }
     model.product.metadata = newMeta;
   }
 });
 // Delete default materials which are a residue of model import
 if (resultObj.material && resultObj.material.length > 0) {
   const materials = resultObj.material.map((mat) => mat.assetId);
   deleteAssets(materials, orgId, authToken);
 }
 return updateAsset(matchingModels, orgId, authToken);
};

const updateTextures = async (resultObj, orgId, authToken) => {
 //Get all texture assets and fabric catalog items
 const promises = [];
 promises.push(getAssetList(orgId, authToken, { tags: 'fabric' }));
 promises.push(getAssetList(orgId, authToken, { type: 'texture' }));
 const [catalogList, textures] = await Promise.all(promises);
 const fabricsCatalog = catalogList.reduce((acc, item) => {
   acc[item.product.name] = item;
   return acc;
 }, {});
 const fabricCode = resultObj.texture[0].name.split('_')[0];

 //Filter out those that don't match the name of new textures
 const resultTextures = resultObj.texture;
 const matchingTextures = textures.filter((texture) =>
   resultTextures.some((result) => result.name === texture.product.name)
 );

 //Confirm new textures exist in library
 resultTextures.forEach((result) => {
   if (
     !matchingTextures.some((texture) => texture.product.id === result.assetId)
   )
     throw new Error(
       `${result.name} assetId: ${result.assetId} not found in asset library.`
     );
 });

 //Add metadata to updates for new textures
 const updates = resultTextures.map((texture) => {
   const splitName = texture.name.split('_');
   return {
     query: {
       id: texture.assetId,
     },
     product: {
       metadata: [
         {
           type: 'String',
           name: 'fabric',
           values: [],
           defaultValue: splitName[0],
         },
         {
           type: 'String',
           name: 'attribute',
           values: [],
           defaultValue: splitName[1],
         },
       ],
     },
   };
 });
 // Add tags to updates for catalog item
 const item = fabricsCatalog[fabricCode].product;
 const clientRejectedIndex = item.tags.findIndex(
   (item) => item === '_client-rejected'
 );
 if (clientRejectedIndex !== -1)
   item.tags[clientRejectedIndex] = '_client-pending';
 ['_tab-material', '_review', '_artist-ready'].forEach((tag) => {
   if (!item.tags.includes(tag)) item.tags.push(tag);
 });
 if (!item.metadata.some((item) => item.name === '*type'))
   item.metadata.push({
     type: 'String',
     name: '*type',
     values: [],
     defaultValue: 'material',
   });
 if (!item.metadata.some((item) => item.name === '*attr'))
   item.metadata.push({
     type: 'String',
     name: '*attr',
     values: [],
     defaultValue: 'Fabric',
   });
 updates.push(fabricsCatalog[fabricCode]);

 //Delete old textures
 const texturesForDeletion = matchingTextures
   .filter(
     (texture) =>
       !resultTextures.some((result) => result.assetId === texture.product.id)
   )
   .map((texture) => texture.product.id);
 deleteAssets(texturesForDeletion, orgId, authToken);

 const fabricAssetId = fabricsCatalog[fabricCode].product.id;
 // Start updating
 return updateAsset(updates, orgId, authToken).then(() => {
   // Trigger renders
   Object.entries(RENDER_ASSETS).forEach(
     async ([type, { assetId, stageId, width }]) => {
       console.log(`Rendering ${fabricCode}(${fabricAssetId}) for ${type}`);
       // Render single fabric for given asset
       const options = {
         configuration: {
           Fabric: { assetId: fabricAssetId },
         },
         stageId,
         width: width || 1000,
       };
       renderAsset(assetId, orgId, authToken, options);
     }
   );
 });
};

module.exports = handler;

These are the support functions used in this code:

const axios = require('axios');
const querystring = require('querystring');
const API_PATH = 'https://preview.threekit.com/api/';
const GET_ASSETS = 'products/export/json';

const getAssetList = (orgId, authToken, queryParams) => {
 const url = `${API_PATH}${GET_ASSETS}?orgId=${orgId}&bearer_token=${authToken}&all=true${
   queryParams ? `&${querystring.stringify(queryParams)}` : ''
 }&all=true`;
 return axios({
   method: 'get',
   url,
 }).then((res) => res.data);
};

module.exports = getAssetList;

const fs = require('fs');
const request = require('request-promise-native');
const API_PATH = 'https://preview.threekit.com/api/';
const IMPORT_PATH = 'products/import';

const updateAsset = (pathOrObject, orgId, authToken) => {
 var cleanup = true;
 var filePath = 'temp.json';
 if (typeof pathOrObject === 'object') {
   fs.writeFileSync(filePath, JSON.stringify(pathOrObject));
 } else if (typeof pathOrObject === 'string' && fs.existsSync(pathOrObject)) {
   filePath = pathOrObject;
   cleanup = false;
 } else throw new Error('Error updating. Invalid object or path.');
 const postUrl = `${API_PATH}${IMPORT_PATH}?orgId=${orgId}`;
 return request
   .post({
     url: postUrl,
     headers: { Authorization: `Bearer ${authToken}` },
     formData: {
       file: fs.createReadStream(filePath),
     },
   })
   .then((res) => {
     if (cleanup) fs.unlinkSync('temp.json');
     return res;
   })
   .catch((e) => {
     console.error(filePath, e.message);
   });
};

module.exports = updateAsset;

const axios = require('axios');
const fs = require('fs');
const API_PATH = 'https://preview.threekit.com/api/';
const DELETE_PATH = 'assets/';

const deleteAssets = (arrayOrPath, orgId, authToken) => {
 const idArray = Array.isArray(arrayOrPath)
   ? arrayOrPath
   : JSON.parse(fs.readFileSync(arrayOrPath));
 console.log(`Deleting ${idArray.length} items...`);
 let counter = 0;
 const promises = idArray.map((id) => {
   return axios({
     method: 'delete',
     url: `${API_PATH}${DELETE_PATH}${id}?orgId=${orgId}`,
     headers: {
       Authorization: `Bearer ${authToken}`,
     },
   })
     .then(() =>
       console.log(
         `Deleted asset ${id} - Total: ${++counter}/${idArray.length}`
       )
     )
     .catch((err) => console.log(err));
 });
 Promise.all(promises).then(console.log('Finished.'));
};

module.exports = deleteAssets;

const axios = require('axios');
const API_PATH = 'https://preview.threekit.com/api/';

const renderAsset = (assetId, orgId, authToken, options) => {
 const body = {
   orgId,
   type: 'vray',
   jobName: 'Auto Render',
   settings: {
     output: {
       resolution: {
         width: options?.width || 1000,
       },
     },
   },
 };
 if (options?.stageId) body.stageId = options.stageId;
 if (options?.configuration) body.configuration = options.configuration;
 if (options?.stageConfiguration)
   body.stageConfiguration = options.stageConfiguration;
 if (options?.layerId) body.layerId = options.layerId;
 if (options?.height) body.settings.output.resolution.height = options.height;
 return axios({
   method: 'post',
   url: `${API_PATH}asset-jobs/${assetId}/renders`,
   headers: {
     Authorization: `Bearer ${authToken}`,
     'Content-Type': `application/json`,
   },
   data: body,
 }).catch((err) => {
   console.log(err);
 });
};

module.exports = renderAsset;

Menu

In this article

Overview:

Post-processing imported assets

Webhook: Topic - Job complete | Type: Import | Status: Success

Menu

Webhooks: Use-Cases and Applications

In this article

Overview:

Post-processing imported assets

Webhook: Topic - Job complete | Type: Import | Status: Success

Related articles