Debug incoming webhooks in Google Tag Manager server preview

Mar 15, 2024
Sep 20, 2021

One of the ways to use server-side tracking is to send data directly from your server endpoint — the Google Tag Manager server container. This way, you can avoid using front-end code and JavaScript.

This guide will show you how to send requests to the GTM server using webhooks, how to see and test webhook data in the server GTM debugger.

What are webhooks?Copy link to this section

Webhooks are one of the ways websites or apps can interact with each other. By using webhooks, you can send real-time data from one application to another whenever the event occurs. 

This exchange happens via webhook URL. A webhook URL is provided by the receiving application and acts as a unique identifier that the other application can call when an event occurs.

Let’s say you use Stripe to accept payments on your site. Webhooks is one of the ways Stripe can interact with your CRM to send information about the new charges to the CRM. Another popular way of using webhook is to create a new user in the database when a user fills out a contact form on the website. 

How can you use webhook in server-side tracking?Copy link to this section

Let’s say you want to use pure server-side tracking without using the GA script as a data source for the server container. How can you do that? Where will the server container take data from? One of the ways is to send data to the SGTM directly from your CRM. To do this, you can use webhooks. 

The tricky part starts when you want to test and see data from incoming requests in the server preview. You can see the requests in the server preview mode either because of cookies (gtm_preview, gtm_auth, gtm_debug) or HTTP preview header. 

Using 3rd party cookies is not an option when you want to use webhooks. The only alternative to see incoming webhook in the server GTM is the X-Gtm-Server-Preview HTTP header.

What are the main benefits of using to set up and debug webhooks to server GTM?Copy link to this section

We added a new feature to the admin console that adds Server Preview Header and helps to debug incoming HTTP requests. The logic works like this: you use your server tagging URL inside the webhook URL and add a request path. At the same time, you should add the server GTM preview header in your Stape admin console. 

After the preview header and webhook URL are set up, you can test incoming webhooks. You should use the data client as a processor for the incoming webhook requests. 

It all may sound complicated, but I have a detailed description below. It was created based on a WordPress webhook. This webhook triggers when the user fills out a contact form and sends contact form details to the server container.

How to set up and debug incoming webhooks in the server Google Tag ManagerCopy link to this section

2. Open the GTM server preview mode and copy the X-Gtm-Server-Preview HTTP header. Click three dots in the top right corner -> Click Send requests manually -> Copy the X-Gtm-Server-Preview HTTP header. 

X-Gtm-Server-Preview HTTP header

3. Open your account -> Click settings on the right side of the container for which you want to set up a webhook -> Click preview header config -> Paste the X-Gtm-Server-Preview HTTP header that you’ve copied in the previous step -> Click save.  

Note: The X-Gtm-Server-Preview HTTP header is a dynamic value; it may be changed in a couple of days. Before testing the webhook, make sure that you’ve added an updated preview header. Once you’re done testing the webhook, make sure you remove the HTTP preview header from the admin console.

X-Gtm-Server-Preview HTTP header
X-Gtm-Server-Preview HTTP header

4. Copy tagging server URL inside your account. 

tagging server url in your container

5. Create a webhook. In this example, I will create a WordPress webhook that sends requests every time a contact form is submitted. This request contains form data. I’ve added a webhook name and webhook URL. The webhook name chooses whatever value you want. The webhook URL should contain a Tagging Server URL that you’ve copied from the admin and request path. In my case, it’s /wp-contact-form. Save the webhook.

webhook url

6. This step will configure a client who will listen to the webhook’s incoming requests. First of all, download Data Client from GitHub -> Open the GTM server container templates tab -> Click new in the Clients section -> Click on the three dots in the top right corner -> Click import -> Select the zip file you downloaded from GitHub. When done, publish Data Client. It needs to be published for the first time when you add it.

webhook requests

7. Create a new client -> Type Data Client -> Click More Settings -> Add additional paths. It should be the path that you’ve added to the webhook URL in step 4. In my case, it’s /wp-contact-form. 

create a new client webhook

8. Open the preview mode of the GTM server container and test your webhook. In my case, I’ve filled out a contact form on the test site. Go back to the preview. You should see the Incoming HTTP Request with the request path you’ve added to the webhook URL. This request should be claimed by the Data client. Then, go to the events tab and check what event data you received. You can use event data in the server container.

data client request
event data

9. When you’re done testing, do not forget to remove the HTTP preview header and publish the server container. 

Conclusion:Copy link to this section

Using webhooks is an excellent way to set up server-side tracking. You can utilize webhooks when other methods are impossible (like webhooks from payment processors like Stripe or PayPal)or when you want to avoid using browser tracking and utilize on-server tracing. 

With, using webhooks and debugging will be easier because we built a feature that allows testing webhook requests using the HTTP preview header from the  GTM server. 

If you’re interested in setting up server-side tracking for your website, do not hesitate to contact us.

Got confused?

All it takes is a few simple questions. Click Get help, fill up the form, and we will assist.

Get help
Tagged with:gtm serverWebhook

Host your GTM server at Stape