Resources

VNTANA Webhooks

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.

This page allows you to create new Webhook’s as well as edit existing ones. To create a new Webhook, press the ‘+ Add Webhook’ button in the upper right corner of the page. This will present you with a form.
  • 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

Events are what the Webhook’s monitor, when an event that a Webhook is subscribed to fires, the Webhook will make a request to the endpoint designated when the Webhook was created, passing along certain information for use by this endpoint. There are three categories of Events on the VNTANA Platform: Product, Folder, and User Events.

Product Events

Product Events allow you to subscribe to a number of state changes for Products on the VNTANA Platform, from Product creation to Product deletion, Processing conversion state to Completed conversion state, and more. The Events associated with Products are:
    
     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

There is currently only one Event related to Folders. This Event, client.added, can be subscribed to with a Webhook to notify you when a new Folder has been created within an Organization. Note: in documentation for Webhook’s and the VNTANA API the terms Client and Folder are both used. These are interchangeable terms, however most references in actual API payloads / endpoints Client is used.

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

In order for the Webhook’s you create on the VNTANA Platform to work, you have to set up an Endpoint that the Webhook can make a POST http request to with the relevant data. These endpoints need not be complex and can simply pass the data along to the necessary component of your services. It is highly recommended that you first check the signature provided with the request. To verify the signature provided, you will need the Secret Key generated when the Webhook is created or updated. This can either be copied from the Platform directly using the button shown below, or using the API to retrieve the Secret Key.
The request made by the Webhook will pass two parameters as Headers, X-VNTANA-SIGNATURE and X-TIMESTAMP, as well as all relevant data for the Event that fired as the Request Body. Using the Secret Key, the signature can be verified by reconstructing it and checking it against X-VNTANA-SIGNATURE:
    
     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

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
{
“event”: “product.added”,
“organization”: {
“uuid”: “string”
},
“product”: {
“uuid”: “string”,
“name”: “TestWebhooks”,
“description”: “This is a test of product events”,
“locations”: [],
“tags”: [],
“attributes”: {
“sku”: “2345”,
“color”: “white”
},
“status”: “DRAFT”,
“material”: null,
“optimization”: null,
“asset”: null,
“autoPublish”: false,
“rendererConfigs”: null,
“dracoCompression”: null,
“textureCompression”: null,
“modelOpsParameters”: {
“PIVOT_POINT_ALIGNMENT”: {
“pivotPoint”: “center”
},
“DRACO_COMPRESSION”: {
“enabled”: “false”
},
“ORIENTATION”: null,
“TEXTURE_COMPRESSION”: null,
“OPTIMIZATION”: null,
“AR_SCALING”: null
},
“pipelineUuid”: “87d414ec-e1f3-4fe3-a5f9-ac4b9cdc51f1”,
“preset”: null
},
“client”: {
“uuid”: “string”
}
}

An Example of the data that is retrieved by your endpoint:

1
2
3
4
5
6
7
8
9
10
11
12
13
{
“event”: “client.added”,
“client”: {
“uuid”: “string”,
“name”: “test name”,
“slug”: “test-name”
},
“organization”: {
“uuid”: “string”,
“name”: “123”,
“slug”: “123”
}
}

An example of the data that is received by your endpoint:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
{
“event”: “user.revoked”,
“user”: {
“uuid”: “string”,
“email”: “some.email@email.com”,
“role”: “CLIENT_ORGANIZATION_CONTENT_MANAGER”
},
“organization”: {
“uuid”: “string”,
“name”: “123”,
“slug”: “123”
},
“client”: {
“uuid”: “string”,
“name”: “test-f9”,
“slug”: “test-f9”
}
}

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):

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
@app.route(‘/vntana-webhooks/client-added’, methods=[‘POST’])
def client_added():
payload = None
 
# The webhook secret can either be retrieved via an API call or stored on your end
secret = “XXXXXXXXXXX”
 
try:
# It is highly recommended that you verify the signature is from VNTANA
if verify_signature(request.headers[‘x-timestamp’], request.data, request.headers[‘x-vntana-signature’], secret):
payload = request.json
 
if payload:
if payload[‘event’] == ‘product.completed’:
# Check whether a configurator needs to be created
conf = check_conf(payload[‘product’][‘name’])
# If configurator needs to be created check if it exists
if conf:
# Check if configurator exists
create, conf_uuid = search_configurators(conf_name)
if create:
create_configurator(conf_name, payload[‘product’][‘uuid’])
else:
add_to_configurator(conf_uuid, payload[‘product’][‘uuid’])
 
# Now you can construct the embed link for the Configurator
 
else:
return “Invalid Data”, 402
else:
return “Access Denied”, 403
except (ValueError, TypeError) as e:
return “Invalid Data”, 402
return “Success”, 200

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:

1
https://embed.vntana.com/variant?uuid=af42d054-fa18-444f-9cc8-6f76eda8271f&clientSlug=samples&organizationSlug=demo

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 hereNote: 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.

  1. Log in using an Authentication Key or email / password.

    • Returns an x-auth-token in the Response Headers.

  2. 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.

  3. Generate a Refresh Token for the Organization.

    • Pass the x-auth-token from Step 1 in the Request Headers.

      1
      2
      3
      4
      {
      ‘x-auth-token’ : ‘Bearer ‘ + x_auth_token
      ‘organizationUuid’ : ‘string’
      }
    • Returns the Refresh Token as the Response Header x-auth-token.

  4. 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.

  5. 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.

      1
      2
      3
      4
      5
      {
      ‘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.

1
2
3
Method: GET
URL: /v1/webhooks/events/
Headers: { ‘x-auth-token’ : ‘Bearer ‘ + refreshToken, ‘Content-Type’ : ‘application/json’ }

This will return a list of all events in the Response Body, subdivided into their categories: Product, Folder, and User.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
“response”: {
“totalCount”: 3,
“grid”: [
{
“category”: “product”,
“totalCount”: 12,
“events”: [
{
“name”: “product.added”,
“description”: “Occurs when a new product is created.”,
“uuid”: “1a426e7d-5e41-480c-b00f-9f46ca12e5ca”
},
{
“name”: “product.pending”,
“description”: “Occurs when a product is in the Pending state of conversion.”,
“uuid”: “018481a-dab5-11ec-9d64-0242ac120002”
},
{
“name”: “product.processing”,
“description”: “Occurs when a product is in the Processing state of conversion.”,
“uuid”: “84b62efc-f91b-4b6d-801c-d135874eb89c”
},
{
“name”: “product.completed”,
“description”: “Occurs when a product successfully finishes converting.”,
“uuid”: “6c424e29-9bb1-4109-bcaf-45b5a740463d”
},
{
“name”: “product.terminated”,
“description”: “Occurs when product conversion is terminated.”,
“uuid”: “ec25b6fc-7c3b-41c0-bb8f-db0ac6b3c06c”
},
{
“name”: “product.failed”,
“description”: “Occurs when a product fails to convert.”,
“uuid”: “c39638ec-744e-486d-920a-c7346b9d5679”
},
{
“name”: “product.published”,
“description”: “Occurs when a product is published and the review state is Live.”,
“uuid”: “1691f8d6-4744-463d-9ae3-9949d483d75d”
},
{
“name”: “product.deactivated”,
“description”: “Occurs when a product is deactivated and the review state is Draft.”,
“uuid”: “10347721-608e-4e81-a4df-a296e21c6678”
},
{
“name”: “product.pending_approval”,
“description”: “Occurs when a product is pending approval during review.”,
“uuid”: “81e28b2f-91a2-4715-9364-fb22b7218986”
},
{
“name”: “product.rejected”,
“description”: “Occurs when a product under review is rejected.”,
“uuid”: “4cc9b9a6-af11-4307-8e51-a2f2216f3387”
},
{
“name”: “product.approved”,
“description”: “Occurs when a product under review is approved.”,
“uuid”: “e5acaeee-6f53-4090-b87e-231e12e37dab”
},
{
“name”: “product.deleted”,
“description”: “Occurs when a product is deleted.”,
“uuid”: “b666992a-01d2-421f-8009-3d7f4121e8dc”
}
],
“uuid”: null
},
{
“category”: “folder”,
“totalCount”: 1,
“events”: [
{
“name”: “client.added”,
“description”: “Occurs when a new folder is created.”,
“uuid”: “e661f3ac-d75b-11ec-9d64-0242ac120002”
}
],
“uuid”: null
},
{
“category”: “user”,
“totalCount”: 2,
“events”: [
{
“name”: “user.added”,
“description”: “Occurs when a new user is added to the organization or selected folders.”,
“uuid”: “67891594-d786-11ec-9d64-0242ac120002”
},
{
“name”: “user.revoked”,
“description”: “Occurs when a current user’s access has been revoked.”,
“uuid”: “c59c3401-5d79-4001-a980-a4d723625687”
}
],
“uuid”: null
}
]
}

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:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
Method: POST
URL: /v1/webhooks/
Headers: { ‘x-auth-token’ : ‘Bearer ‘ + refreshToken, ‘Content-Type’ : ‘application/json’ }
Request Body: {
“clients” : [ “some-client-slug” ],
“description” : “Description of the Webhook”,
“disable” : true,
“events” : [
{
“name”: “product.added”,
“description”: “Occurs when a new product is created.”,
“uuid”: “1a426e7d-5e41-480c-b00f-9f46ca12e5ca”
}
],
“name” : “Name of Webhook”,
“organizationUuid” : “string”,
“url” : “string”,
“userEmail” : “string”
}
  • 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:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
Method: PUT
URL: /v1/webhooks/{uuid}
Headers: { ‘x-auth-token’ : ‘Bearer ‘ + refreshToken, ‘Content-Type’ : ‘application/json’ }
Request Body: {
“clients” : [ “some-client-slug” ],
“description” : “Description of the Webhook”,
“disable” : true,
“events” : [
{
“name”: “product.added”,
“description”: “Occurs when a new product is created.”,
“uuid”: “1a426e7d-5e41-480c-b00f-9f46ca12e5ca”
}
],
“name” : “Name of Webhook”,
“organizationUuid” : “string”,
“url” : “string”,
“userEmail” : “string”,
“uuid” : “string”
}

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:

1
2
3
Method: GET
Endpoint: /v1/webhooks/{webhookUuid}
Headers: { ‘x-auth-token’ : ‘Bearer ‘ + refreshToken, ‘Content-Type’ : ‘application/json’ }

An example response looks like:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
{
“success”: true,
“errors”: [],
“response”: {
“userEmail”: “some.email@example.com”,
“name”: “Some Webhook”,
“description”: “”,
“disable”: false,
“secret”: “XXXXXXXXXXX”,
“url”: “your-endpoint-url”,
“organizationUuid”: “string”,
“events”: {
“totalCount”: 1,
“grid”: [
{
“category”: “product”,
“totalCount”: 1,
“events”: [
{
“name”: “product.completed”,
“description”: “Occurs when a product successfully finishes converting.”,
“uuid”: “6c424e29-9bb1-4109-bcaf-45b5a740463d”
}
],
“uuid”: null
}
]
},
“clients”: [
“some-client-slug”
],
“uuid”: “string”,
“created”: “2022-06-17T00:37:20.365139”,
“updated”: “2022-06-17T00:37:20.365139”
}
}

Now, to retrieve a list of all Webhook’s in an Organization, call the following endpoint:

1
2
3
Method: GET
Endpoint: /v1/webhooks/organization/{organizationUuid}
Headers: { ‘x-auth-token’ : ‘Bearer ‘ + refreshToken, ‘Content-Type’ : ‘application/json’ }

An example of a response from the above endpoint is:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
{
“success”: true,
“errors”: [],
“response”: {
“totalCount”: 1,
“grid”: [
{
“userEmail”: “some.email@example.com”,
“name”: “Webhook Name 1”,
“description”: “”,
“disable”: false,
“secret”: “XXXXXXXXXXX”,
“url”: “your-endpoint-url”,
“organizationUuid”: “string”,
“events”: {
“totalCount”: 3,
“grid”: [
{
“category”: “product”,
“totalCount”: 2,
“events”: [
{
“name”: “product.added”,
“description”: “Occurs when a new product is created.”,
“uuid”: “1a426e7d-5e41-480c-b00f-9f46ca12e5ca”
},
{
“name”: “product.pending”,
“description”: “Occurs when a product is in the Pending state of conversion.”,
“uuid”: “018481a-dab5-11ec-9d64-0242ac120002”
}
],
“uuid”: null
},
{
“category”: “folder”,
“totalCount”: 1,
“events”: [
{
“name”: “client.added”,
“description”: “Occurs when a new folder is created.”,
“uuid”: “e661f3ac-d75b-11ec-9d64-0242ac120002”
}
],
“uuid”: null
},
{
“category”: “user”,
“totalCount”: 2,
“events”: [
{
“name”: “user.added”,
“description”: “Occurs when a new user is added to the organization or selected folders.”,
“uuid”: “67891594-d786-11ec-9d64-0242ac120002”
},
{
“name”: “user.revoked”,
“description”: “Occurs when a current user’s access has been revoked.”,
“uuid”: “c59c3401-5d79-4001-a980-a4d723625687”
}
],
“uuid”: null
}
]
},
“clients”: [],
“uuid”: “string”,
“created”: “2022-06-08T13:53:31.235656”,
“updated”: “2022-06-08T13:53:31.235656”
}
]
}
}

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:

1
2
3
Method: PATCH
Endpoint: /v1/webhooks/{webhookUuid}/secret
Headers: { ‘x-auth-token’ : ‘Bearer ‘ + refreshToken }

Upon successful regeneration, the endpoint will return a Response Body similar to that of the Get Webhook requests.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
{
“errors”: [
“string”
],
“response”: {
“clients”: [
“string”
],
“created”: “2022-06-21T03:34:10.348Z”,
“description”: “string”,
“disable”: true,
“events”: {
“grid”: [
{
“category”: “string”,
“events”: [
{
“description”: “string”,
“name”: “string”,
“uuid”: “string”
}
],
“totalCount”: 0,
“uuid”: “string”
}
],
“totalCount”: 0
},
“name”: “string”,
“organizationUuid”: “string”,
“secret”: “string”,
“updated”: “2022-06-21T03:34:10.348Z”,
“url”: “string”,
“userEmail”: “string”,
“uuid”: “string”
},
“success”: true
}

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.

On This Page

Accelerate Your
Digital Transformation

Learn how our platform can automate your 3D process.

Tap the magnifying glass to the left of your screen to search our resources.