Configuring Webhooks in Wingify FullStack

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

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

Whenever you create a FullStack campaign in Wingify, 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 Wingify 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 Wingify offers to detect the change and update the settings file.

One way to detect the change in the settings file is by polling the Wingify servers frequently, and when detected, update the settings file with it. This increases the load on your server as you need to poll the Wingify 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 Wingify enable you to subscribe to changes. Anytime there is a change in the FullStack campaign settings, Wingify 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. Wingify keeps you up-to-date.

For example, as soon as the traffic allocation percentage of a variation is changed from the app, Wingify 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 Wingify.

Advantages of Using Webhooks in Wingify

• 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 Wingify

Earlier, Wingify 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, Wingify 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 Wingify 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.
   
   Note:
   1. In case you are an existing user, workspace-level webhooks will continue to be available if you are already using them. To opt for environment-level webhooks, reach out to support@wingify.com. 
   2. Once you choose to use environment-level webhooks, the workspace-level option gets disabled. 
   3. Workspace-level webhooks will not be available for those availing the webhooks option for the first time.
   4. If you have workspace-level webhooks enabled, you can manage them by going to Profile menu > Settings > Campaign > Enable Webhooks section.

Payload Format

Below is the payload format used by Wingify.

{
 "timestamp": 1606482285,
 "event": "settings_changed",
 "action": "campaign_settings_changed",
 "triggered_by": "vwo"
}

Usage

// Assuming Express server
const express = require('express');
const app = express();
// Endpoint to subscribe to changes made in VWO FullStack campaigns
app.post('/vwo-webhook', (_ree, res) => {
 console.log('\nWebhook Triggered!');
 // You may want to fetch the updated settings so that SDK can use the same
 vwoClientInstance.getAndUpdateSettingsFile()
   .then(latestSettings => {
     console.log(latestSettings);
     res.end(JSON.stringify({
       status: 'success',
       message: 'Webhook received and Settings-file updated successfully'
     }));
   });
});
app.listen(4000, () => {});

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 Wingify and not from any third-party service trying to trigger the Wingify configured webhook manually.

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

On enabling the webhooks in Wingify, 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.
   
   Note: Please ensure to keep your secret key secure and private.