Debug incoming webhooks in Google Tag Manager server preview

One of the ways to use server-side GTM 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.

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. 

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.

We added a new feature to the stape.io 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.

1. Create and set up a Google Tag Manager server container.

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. 

3. Open your stape.io 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 stape.io admin console.

4. Copy tagging server URL inside your stape.io account.

4.1. Go to Settings and click on three dots on your domain -> View details. 

4.2. On the right side you'll see the records. Copy Subdomain name.

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 Stape admin and request path. In my case, it’s /wp-contact-form. Save the webhook. For WooCommerce server-side tracking, webhooks are also used for order events like Purchase and Refund, so the same preview logic helps check the data before publishing.

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.

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. 

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.

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

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 stape.io, 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.