Implementing your own Webhooks

Before you start

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

  • Webhooks that transmit data on 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:

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:

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 image pixel

  • javascript

  • An iframe (inline frame)

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 image pixel

Compared to the other Webhook types, implementing an image pixel is relatively easy. All you need to do is go through the following 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 ‘tracking 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. Your URL will be activated immediately, because image pixels do not require approval from the platform administrator.

If you want basket details to be transmitted via Webhooks, please read the section on image pixels in the article on transmitting basket details. Note that baskets are only available for browser-side Webhooks.

Implementing an iframe or a javascript

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:

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

Webhooks with browser-side delivery 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.

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