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.
Note: This guide covers integrating with Webhooks via the VNTANA Admin API. For a more general guide on Webhooks go here.
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. For more information on this, please view our guide on creating Webhook’s and your own endpoints.
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.
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.