With the Webhooks feature now available on the VNTANA Platform, you can subscribe to a number of events on the Platform for automatic notification when these events fire. This allows for greater control over the integration of the VNTANA Platform in your workspace while reducing the need for repetitious API calls for similar effect. For example, by creating a Webhook linked to a particular Client / Folder on the Platform, your services can be automatically notified when a new Product has been created as well as when said Product has finished conversion, allowing you to handle the Product’s information as you see fit without the need to continuously scan via an API call for any new Products or Completed Products.
Creating a Webhook
To create a Webhook, you must first sign in to your VNTANA Platform account here. Once authenticated and viewing the dashboard of the Organization you wish to create the Webhook in, click the ‘Manage’ button at the bottom of the left navigation pane.
From here select the ‘Webhooks’ option from the list of Organization settings categories.
- Name: [Required] Simply the desired name of the Webhook. This does not need to be unique.
-
URL: [Required] The full URL of the endpoint the Webhook will make a request to upon the set event’s firing.
-
Description: [Optional] A simple description of the Webhook.
-
Select Folders: [Optional] Set all Folders (Clients) the Webhook should apply to. If none are selected the Webhook will apply to all Folders in the Organization.
-
Events: [Required] Select all events the Webhook should monitor.
When a Webhook is created, an UUID will be generated to identify the Webhook, as well as a Secret Key, which can be used to verify the signature from the Webhook when it is received by your Endpoint. This Secret Key can either be copied from the Platfrom as below, or retrieved via the VNTANA API.
When the Webhook sends a request to the designated Endpoint, it will pass a payload containing relevant data based on the type of Event that fires (link to information on Events) as a Request Body. Additionally, it will pass two Request Headers: X-VNTANA-SIGNATURE and X-TIMESTAMP.
X-VNTANA-SIGNATURE = HMAC_256(Timestamp + "#" + payload)
This uses the Secret Key for the Webhook to hash a Timestamp of the Event and the data Payload that is passed in the Request Body. The Timestamp is the X-TIMESTAMP header which is UTC time in ISO8601 format.
To see some examples on creating Endpoints to retrieve data from a created Webhook, view the guide below.
Events
Product Events
product.added
product.pending
product.processing
product.completed
product.terminated
product.failed
product.published
product.deactivated
product.pending_approval
product.rejected
product.approved
product.deleted
Folder Event
User Events
There are two Events available related to Users in an Organization: user.added and user.revoked. These can be subscribed to with a Webhook to notify when a user is added to the Organization as well as when a user is removed from the Organization. For more information on Users and how to add/remove Users from the Platform, visit this guide.
Creating Endpoints
X-VNTANA-SIGNATURE = HMAC_256(Timestamp + "#" + payload)
The X-VNTANA-SIGNATURE is a hashed message consisting of X-TIMESTAMP, ‘#’, and the payload passed in the Request Body. The X-TIMESTAMP is UTC time in ISO8601 format.
Each type of Event will pass specific data in the Request Body. The data passed can be seen below. Additionally, some example Endpoints for the Webhook’s to call are provided as well. A recommended solution to test these is to utilize ngrok to point traffic to your localhost allowing you to create endpoints with temporary URL’s.
When creating the endpoints, you will need to handle the information that is passed along. Depending on the type of event, this information may differ. Below are example payloads from the three types of events:
An example of the data that is retrieved by your endpoint
An Example of the data that is retrieved by your endpoint:
An example of the data that is received by your endpoint:
The provided code samples are designed to utilize a single endpoint for all events. Though a viable solution to integrating with VNTANA Webhook’s, it is not the only way to handle them. A single endpoint can be created for every Event, or for each category, or even any combination of events. Likewise, a single Webhook can be created for the entire Organization, or a Webhook can be created for each Client / Folder.
Example Implementation
VNTANA Webhook’s are designed to seamlessly integrate with the VNTANA Admin API, allowing you to largely remove the need for manual interaction to showcase your 3D assets. As an example, we will walk you through how you can make use of both Webhook’s and the API to automatically add newly created Products to Configurators as well as generate an iframe or embed link for this Configurator.
The first step in the process is to create the Webhook. A simple Webhook can be employed which only subscribes to the the events product.added and product.completed for the whole Organization or just for a selection of Client’s / Folder’s. The endpoint you must create which is called by this Webhook will check for these, and depending on which event fires, will direct the information accordingly.
An example of your endpoint may look like this (written in Python using Flask):
In order to keep this example simple, the full methods are not fleshed out, however we will go through each of the steps here. First, before any of the following endpoints, you would need to ensure you have proper Authentication.
verify_signature: [Line 10] When this endpoint receives a request from the Webhook, it will first verify the signature by reconstructing it using the Webhook’s secret. See the code samples above to see how this is handled.
check_conf: [Line 16] This method is up to you and your needs. Theoretically this method would work by checking your systems for information that indicates whether the Product sent in the request expects to be added to a Configurator.
search_configurators: [Line 20] This method will make an API request to the VNTANA endpoint /v1/variant-groups/search to check whether there already exists a Configurator in which the Product in question could or should be added to. This search can occur by checking the name of the Configurator, checking the Product UUID’s that may already exist in the Configurator, or checking the Tags for the Configurator to determine if any returned Configurators are correct. For more information on searching Configurators, view this guide.
create_configurator: [Line 22] If no Configurator exists that matches your criteria, this method will make an API request to the endpoint /v1/variant-groups to create the needed Configurator and add the Product to it. For more information on creating a Configurator see this guide.
After handling the newly optimized Product by creating a Configurator and adding it, you can construct the embed link and / or iframe for this Configurator. The base URL for an embed link is https://embed.vntana.com with the Configurator version being https://embed.vntana.com/variant. From here to create the full embed link you need three pieces of information:
organizationSlug: Retrieved via API Get Organizations request.
clientSlug: Retrieved via API Get Clients request.
uuid: The UUID of the Configurator, returned in the response body of a successful search or creation request.
An example of a full embed link is:
For more information on any of these values, see the API Overview.
Webhook Errors
If there are any issues with the creation of your Webhook or endpoint which prevents the Webhook from making a successful request, the Webhook will retry a certain number of times before sending the following email to the email of the User that created the Webhook:
If the issue with the Webhook is not addressed, it will eventually be disabled. The following email will be sent to the User’s email that created the Webhook:
These issues are typically related to an incorrect URL where the request is receiving a 500 http response as it cannot reach the endpoint you’ve entered. Note: if the Webhook is created via the API, make sure the email you enter is correct as it will store that email for correspondence. This isn’t a concern when making the Webhook on the Platform as it just stores the email of the logged in User.
Webhooks API Integration
API Base URL: https://api-platform.vntana.com
For a collection of all Endpoints in our Admin API, view the documentation here. To view the collection of Public Endpoints, view the documentation here. Note: In the following guide and aforementioned documentation, you will see referenced in numerous Endpoints something called a Client. This refers to the folders one can create on the Platform within an Organization. The Client nomenclature is a legacy reference being replaced with Folder. These will be referenced as Client / Folder in all guides.
Webhook’s allow you to subscribe to certain events on the VNTANA Platform, automatically retrieving notifications and information when these events fire. This service allows you to retrieve notice when a Product has been created or when it has completed it’s conversion without needing to repetitiously make API calls to check on new Products or their statuses.
With the release of VNTANA Webhook’s, the VNTANA Admin API has been updated to allow for the creation, retrieval, and deletion of Webhook’s automatically. As with any usage of the VNTANA Admin API, one must first generate the appropriate level of authentication, retrieving a Refresh Token from the Platform. View this guide on authentication through the API for more information.
-
Log in using an Authentication Key or email / password.
-
Returns an x-auth-token in the Response Headers.
-
-
Retrieve a list of Organizations and store the needed Organization’s UUID.
-
Pass the x-auth-token from Step 1 in the Request Headers.
1{ ‘x-auth-token’ : ‘Bearer ‘ + x_auth_token } -
This step can be skipped if the Organization UUID is already stored locally.
-
-
Generate a Refresh Token for the Organization.
-
Pass the x-auth-token from Step 1 in the Request Headers.
1234{‘x-auth-token’ : ‘Bearer ‘ + x_auth_token‘organizationUuid’ : ‘string’} -
Returns the Refresh Token as the Response Header x-auth-token.
-
-
Retrieve a list of Clients / Folders and store the needed UUID.
-
Pass the x-auth-token in the Request Headers.
-
This step can be skipped if the Client / Folder UUID is already stored locally.
-
-
Generate a Refresh Token for the Client / Folder (Organization Admin / Owner users must skip this step).
-
Pass the Refresh Token from Step 3 in the Request Headers with the Organization and Client UUID’s.
12345{‘x-auth-token’ : ‘Bearer ‘ + refreshToken,‘organizationUuid’ : ‘string’,‘clientUuid’ : ‘string’} -
Returns the Refresh Token as the Response Header x-auth-token.
-
Retrieving Events
Webhook’s work by subscribing to one or more events in your Organization and making a POST http request to an endpoint of your design containing relevant information to that event. When interacting with Webhook’s via the VNTANA API, it is necessary to have the information regarding these events before doing anything else. By making a call to the following endpoint you can retrieve the list of all events available to subscribe to.
This will return a list of all events in the Response Body, subdivided into their categories: Product, Folder, and User.
Each event contains a name which is passed by the Webhook to your endpoint and can be used to verify what event fired, otherwise the UUID is needed when using the VNTANA API to create Webhook’s and should be pulled from this list.
Creating or Updating a Webhook
Once you know the UUID’s of all events you wish to create Webhook’s for, it is time to either create or update a Webhook. First, to create a Webhook, call the following endpoint:
clients: List of client slugs for the Webhook to monitor events in.
description: Simple description of what your Webhook does.
disable: Boolean indicating whether the Webhook is Enabled or Disabled.
events: List of all events to subscribe to, exact same information for each event as returned by the GET events endpoint.
name: The name of your Webhook.
organizationUuid: The UUID of the Organization the Webhook monitors.
url: The URL of the endpoint the Webhook will call when an event fires.
userEmail: Your user email.
This will return almost the same information in the Response Body, with an additional parameter: uuid. This is the unique identifier for the Webhook and will be used with further API calls to interact with this Webhook.
To update a Webhook, call the following endpoint:
As you can see the Request Body is the same as creating a Webhook with one addition: uuid. This is the UUID returned in the Response Body when creating the Webhook or when searching for Webhooks.
Searching for Webhooks
There are two methods to search for a Webhook, directly with the Webhook’s UUID or by searching all Webhook’s within an Organization. If you already know the Webhook’s UUID then you can directly retrieve its information using the following endpoint:
An example response looks like:
Now, to retrieve a list of all Webhook’s in an Organization, call the following endpoint:
An example of a response from the above endpoint is:
Both endpoints return the same data per Webhook, the difference of course being in the ability to retrieve all the information on an Organizations set of Webhook’s in one go with the latter endpoint.
Updating a Webhook Secret
The most important aspect of the Webhook is the Secret Key. This is generated when the Webhook is created and is used to hash the data sent by the Webhook to create a signature which you can use in your endpoints to verify that the data is legitimate. You would use this Secret Key to reconstruct the hashed message and verify that they are equivalent.
Should you need to regenerate the Secret Key of any of your Webhook’s you can use the following endpoint:
Upon successful regeneration, the endpoint will return a Response Body similar to that of the Get Webhook requests.
The new secret can be pulled from this data and stored locally if so desired, otherwise anytime you need to verify a Webhook signature you can make a call to one of the Get Webhook endpoints to retrieve the Secret Key.
To test any of the Webhook endpoints, use the below Postman collection. The collection contains all Webhook endpoints but is not set up to simply be run as a full collection like our other collections. The endpoints to get Events and Webhook’s and Secret regeneration can be use together as a full collection, you need only set the necessary global variables, but the rest of the endpoints require a bit more information, namely the events, and so those would need to be set up manually. With their information manually entered you will be able to run them with others as a collection. If you just wish to run the endpoints individually, simply activate all deactivated endpoints and fill in all necessary data for each endpoint. You can view a more general guide on our Postman collections here.