Configuring Webhooks in VWO FullStack

In this article, we’ll learn about the concept of webhooks in VWO, its advantages, how you can enable it, and how you can secure your webhooks.

To better understand the concept of webhooks in VWO FullStack, let's first learn about the settings file.

Whenever you create a FullStack campaign in VWO, a settings file corresponding to your campaign configurations is generated, which you could fetch and cache on your server. If any campaign setting(s) are modified via the VWO app, the settings file stored at your server needs to be updated. This ensures that your campaigns are always running on the latest configurations.

Let's look at the different options that VWO offers to detect the change and update the settings file.

One way to detect the change in the settings file is by polling the VWO servers frequently, and when detected, update the settings file with it. This increases the load on your server as you need to poll the VWO servers at a regular interval, say every ten minutes.

Another way to detect the change in the settings file is by using webhooks. Webhooks in VWO enable you to subscribe to changes. Anytime there is a change in the FullStack campaign settings, VWO sends an HTTP POST call with a payload to the configured URL. Therefore, you know when to fetch the settings file. It helps you to keep the most up-to-date version of the settings file.  

With webhooks in place, you don't have to worry whether or not you are using the updated settings file. VWO keeps you up-to-date.

For example, as soon as the traffic allocation percentage of a variation is changed from the app, VWO sends an HTTP POST call with a payload to notify about the change in the campaign settings. 

To get notified about the change in the settings file, all you need to do is enable the webhook setting and specify the URL where you wish to receive the change event notification. To know how to do this, refer to Enabling Webhooks in VWO.

Advantages of Using Webhooks in VWO

• Eliminates the need to frequently fetch the latest campaign settings file, reducing the load on your servers.
• Eliminates the possibility of using the old campaign settings file, if not fetched in short intervals.

Enabling Webhooks in VWO

Earlier, VWO used to provide webhooks that notified the changes in the campaign settings at the workspace level. However, these notifications were generic and spanned across the environments. This led to guessing which developer environment should be updated whenever you update or create a new A/B test, Feature Test or Feature Rollout. Thereby, VWO has stepped up further to a more granular approach that allows configuring webhooks at environment-level.

Now, you avail the flexibility to configure webhooks individually for each environment. By enabling these webhooks, you will be notified each time a change is made in the campaign settings specific to the given environment. To subscribe to the environment-specific changes, enable the webhooks under the required environment(s).

Procedure

1. Log in to your VWO account.
2. From the left panel, go to FullStack > Projects and select a project.
   
   NOTE: We are introducing a module called, Websites and Apps, which is available under the early access program and will be rolled out in phases. If your account is enabled with the Websites and Apps module, you can find your projects under Configurations > Websites and Apps > Websites and Apps. To configure your project, select the project and click on the Configuration tab.
3. Under the Environment(s) section, select the Enable Webhooks option for those environments that you prefer to subscribe to the changes.
4. In the Webhook URL field, enter the URL where you wish to receive the change event notification.
   
5. To finalize your settings, click Save.

Payload Format

Below is the payload format used by VWO.

Usage

Retrying Webhooks

In case the webhook URL is down (or we receive a non 200 response for the POST request), the webhook would be retried for the next 1 hour after every 1-2 seconds.

Securing Webhooks with API Key-based Authentication

When you set up a public endpoint for updating campaign settings, you may want to protect your webhook to ensure that notifications come from VWO and not from any third-party service trying to trigger the VWO configured webhook manually.

While configuring the webhook in VWO, you can secure it by generating a secret key sent in the x-vwo-auth header of the POST request by VWO. You can then compare this key to ensure that the requests are sent via VWO and not by other third-party services. 

On enabling the webhooks in VWO, a secret key is automatically generated along with it. To generate a new secret key for the same, perform the following steps:

Procedure

1. Click the Regenerate Key button. The Regenerate Secret Key dialog appears.
   
   
2. Click the Generate Key button in the dialog and save the change.