Implementing your own Webhooks

Before you start

It is important to make a distinction between the following types of Webhooks:

• Webhooks that transmit data of on-site behaviour of customers. These Webhooks need to be implemented in the container tag manager, which allows them to be fired on the website of the Advertiser. Please note that you cannot implement these Webhooks yourself. If you want them to be implemented, make sure you contact the support team of your platform.

• Webhooks that transmit data related to conversions. You can implement these Webhooks yourself by following the instructions below.

Getting started

Make sure you are logged in to your Partner UI and click on Webhooks -> Manager in the navigation menu. If you do so, a page will appear looking more or less like this:

Open

You will see the page has two sections: one for the Webhooks rules and one for the target Configurations. The rule defines under which conditions the target configuration you implement is fired. Under target configuration, you can register the actual http calls and define the parameters.

Implementing the target configuration

Overview

To implement a new target configuration, please click on the button create new target configuration in the target configuration section of the page. If you do so, a page will appear looking more or less like this:

Open

Configuration of a webhook target

The further proceedings depend on the type of Target configuration you are implementing. Currently, three types can be implemented:

• An URL-based

• A javascript (only for browser-side, deprecated)

• An iframe (only for browser-side, inline frame, deprecated)

Because they can effect the performance of the advertiser’s confirmation page, javascripts and iframes need to be approved by the platform administrator before they are activated.

Implementing an URL-based webhook

Please follow this steps:

1. Enter a name and a description of your target configuration. Please do not activate the advanced mode, because it is only relevant for javascripts and iframes.

2. Proceed to paste your target URL into the field under the header Target URL.

3. Define the parameters in your URL. After you have pasted in your URL, the platform will automatically recognize all the parameters.

   • If you are using dynamic parameters, you need to make sure they are filled with the correct placeholders. To do this, you need to select the relevant placeholders from the panel on the right of the page and drag and drop them into the fields under ‘parameter value’. Please note that here are four types of placeholders:

• Essential placeholders transmitting values for the order ID, the order value and the currency of the conversion.

• Extended placeholders transmitting values such as the sub ID, the timestamp and the ad media ID.

• Placeholders that can only be used when the tracking service you implement uses the browser delivery method.

• Placeholders that can only be used when the tracking service you implement uses the server to server delivery method.

When you have selected the relevant placeholders for your dynamic parameters, all you have to do is click save at the bottom of the page.

If you want basket details to be transmitted via Webhooks, please read the section on image pixels in the article on transmitting basket details.

Advanced mode: Implementing an iframe or a javascript

advanced mode (deprecated)

iFrame and javascript are only available for Webhooks with browser-side delivery, which are deprecated, because they typically rely on 3rd-party tracking or 3rd-party JavaScript code loading. Due to browser restrictions with ITP/ETP, and future limitations of browsers, you should migrate from Webhooks using server-side delivery.

To implement an iframe or a javascript, make sure you go through the following steps:

1. Start by giving your target configuration a name and a brief description.

2. Proceed to activate the advanced mode by hitting the tick box. If you do so, you will see a new section appearing at the bottom of the page, called ‘tracking HTML codes’.

3. Before you implement the iframe or the javascript , make sure you implement an image pixel under ‘tracking URL’. This is not mandatory, but it is recommendable as the image pixel can be used as a backup when your iframe or javascript cannot be fired because the customer’s browser settings are blocking iframes and javascript. If your image pixel contains dynamic parameters, make sure you add the correct placeholders.

4. When you have created the fallback, scroll down the page to the ‘tracking HTML codes’ section. This section will look more or less like this:

Open

In this section, go through the following steps:

1. Remove all script that is visible in the field under ‘new version’ and replace it with the iframe or javascript you want to implement. In case you hadn’t implemented any javascript yet, the field under previous version will be empty. If you are replacing or editing a javascript or iframe, this field will contain the javascript you have implemented earlier.

2. Make sure all dynamic parameters are filled with the right placeholders. These placeholders can be copied directly from the panel above the field where you paste the new javascript. Please note there are essential placeholders (order ID, order value and currency) and extended (such as ad media ID, timestamp and conversion site ID). If you want the javascript to transmit basket details, please read the section on javascript in the article on transmitting basket details via Webhooks.

3. Further below in the section, you can write a comment for the platform administrator related to the iframe or javascript you want to implement, explaining the purpose of the iframe or javascript you are implementing, for example.

4. As was mentioned above, your iframe or javascript needs to be approved by the platform administrator before it is activated. To request approval, select the tick box ‘save and request approval’ under ‘approval workflow state’. If you do not want to request approval yet, select the tick box ‘save, but do not request approval’.

When you are ready, please do not forget to click ‘save’ at the bottom of the page.

Editing a target configuration

If you want to edit a target configuration, just click on the  icon in the target configuration panel on the overview page. If you do so, you will be taken to the same page on which you have implemented your target configuration. Please note that changes in implemented iframes and javascripts need to be approved by the platform administrator again. You can use the section below the comments to compare differences between the new version and the previous one. The versions can be displayed next to each other and on top of each other.

Removing a target configuration

Before you are able to remove a code set, you need to make sure all tracking services connected with the code set have been removed. If this has been done, you will see a small  appear next to the code set in the code set panel. If you click on this icon and confirm your action in the system window, the code set will be removed.

Creating a new rule

After you have implemented your target configuration, you need to create a rule. The rule defines under which conditions the target configuration you have implemented is activated. To create a rule, go back to page with the overview of all Webhooks. Go to the panel Rules and click on the button ‘create new rule in the right lower corner of the page. If you do so, a new row will be added to the panel, looking more or less like this:

wFrom left to right, following settings have to be defined:

• Under ‘Rule’, you give your rule a name.

• Under ‘code set’, you select the code set for which the service is created.

• Under ‘Delivery’, you select the delivery method. Possible options are browser side, server side or both:

  • Use server side for server side delivery. Server side delivery is more accurate and allows you to transmit additional data, such as the commission model.

• Use browser side for javascript and iframes without an image pixel as backup. Browser side delivery can be used for image pixels as well, but is not recommended.

• Use both for javascript and iframes with an image pixel as backup. In this case, the javascript and iframes can be delivered properly and, in case they are blocked, the image pixel will be fired with the highest accuracy.

• Under ad space, you select the Adspace for which the rule is relevant. If the rule is relevant for all your Adspaces, just select ‘all’.

• Under Advertiser, you select the Advertiser for which the target configuration should be fired. Please note you can only select Advertisers when you have been admitted to their programs.

• Under Conversion Target, you select the Conversion Target for which the rule should be fired. Please note the available Conversion Targets will depend on the Advertiser you select in the column before.

• Under Tracking Category, you select the Tracking Category for which the target configuration should be fired. Unless you have implemented a very specific target configuration, it is recommended to select all here.

• To activy your rule, make sure you select active under status.

To save your service, please click on the  icon.

Editing a rule

To edit a tracking service, all you need to do is click on the  icon in the panel. If you do so, you will see all values are unlocked. Change whatever you want and click on the  icon in the panel.

Removing a rule

You can remove a rule by clicking on the  icon in the rule panel and confirming your action in the system window appearing after you’ve clicked the icon. You can also choose to deactivate the rule by changing the status.

Creating replacements

Do I need to create replacements?

You only need to create replacements when the format of the values in the code’s parameters in your tracking configuration does not match with the format of your own system. In this case, a replacements will make sure that any sequence of characters is replaced by another sequence of characters you define. For example, you could use replacements to translate the names of Conversion Targets or Tracking Categories.

Creating replacements

To create a replacement set, make sure you go through the following steps:

• Go to the overview page and look at the Replacements panel at the bottom of the page.

• Click on the button ‘create new replacements’ in the lower right corner of the panel.

• In the window appearing now, give your replacements a name and a brief description.

• Proceed to click the button ‘add new replacement’. Fill out the value you want to replace under ‘original value’ and the value you want it to replaced by under ‘replace with’.

• To add more values, just click on the button ‘add new replacement’ again. To remove values, click on the icon next to them.

• When you are ready, click on the button ‘save’. If you do so, you will find the replacements added to the overview.

• Finally, make sure you activate the replacements by adding it to one or more rules. To do so, edit the rule and select it under ‘Replacements’.

Using the logs to troubleshoot server-side Webhooks

Webhook logs allow you to troubleshoot server-side Webhook executions. You will find comprehensive information in this article: Using the logs to troubleshoot server-side Webhooks

Testing Webhooks

Webhooks call your system and pass parameters. If you don’t have a testing area within your system, or your system is limited in terms of looking in to logs, you can you publicly available webhook-systems for testing purposes. This way your webhooks are executed, and you can debug the results.

There are several webhook-testing systems available:

Using Postman-Echo

1. Use https://postman-echo.com/get as your target URL. For example:

https://postman-echo.com/get?ADVERTISER_MID=#{ADVERTISER_MID}&WINNER_AMC_ADSPACE_ID=#{WINNER_AMC_ADSPACE_ID}&...

2. Use the the webhook logs to see your webhooks in action:

Using the logs to troubleshoot server-side Webhooks

Using PostBin

To test webhooks, we recommend to use PostBin (https://www.toptal.com/developers/postbin/).

1. Create a new bin

Open

2. Your “bin” will get a unique Url, which you should write down. It has this form:

https://www.toptal.com/developers/postbin/${UNIQUE_ID}

Open

3. You now can use the URL of your “bin” in your Webhook target URL for testing, for example:

https://www.toptal.com/developers/postbin/${UNIQUE_ID}?ADVERTISER_MID=#{ADVERTISER_MID}&WINNER_AMC_ADSPACE_ID=#{WINNER_AMC_ADSPACE_ID}&...

4. When the Ingenious-system fires a Webhook, you then can refresh you “bin” url in the browser to see incoming webhooks:

Open

5. Use also the webhook logs to see your webhooks in action:

Using the logs to troubleshoot server-side Webhooks

Using RequestCatcher

1. Open this website, and keep the website open:

https://wehook-test.requestcatcher.com

2. Configure the Target-URL of your webhook, for example:

https://wehook-test.requestcatcher.com/test?ADVERTISER_MID=#{ADVERTISER_MID}&WINNER_AMC_ADSPACE_ID=#{WINNER_AMC_ADSPACE_ID}&WINNER_AMC_ADMEDIA_ID=#{WINNER_AMC_ADMEDIA_ID}&...

3. Once a webhook is called, the website will show the call

4. Use also the webhook logs to see your webhooks in action:

Using the logs to troubleshoot server-side Webhooks