Using the Custom Webhook to send data to Heap

[InvocaKnowledge]

Symptoms

• Send Invoca call data and Signals to Heap

Applies To

• Updating the tag to capture the Heap User ID and Session ID
• Utilizing the Post-Call Custom Webhook feature

Resolution

Before implementing any updates in Invoca, it's crucial to consider the following steps that require the involvement of a Heap Technical Resource:

1. Collaborate with your Heap Technical Resource to enable the Invoca Tag to retrieve the Heap Session ID and User ID from the dataLayer. In this particular use case, the Tag can extract the Heap Session ID using the heap.getSessionId() function and the Heap User ID from the heap.userId variable.

2. Work closely with your Heap Technical/Developer Resource to configure your Heap platform to accept two additional parameters in the Track server-side API: user_id & session_id. These parameters need to be dynamically passed in the API call.

Both of these tasks must be completed before any configuration can be implemented in Invoca.

Once these prerequisites are met, follow these steps:

1. Create two new Marketing Data Fields:

   • heap_userID
   • heap_getSessionId

2. Generate a new draft of your Invoca Tag to extract values from the dataLayer. Consult your Heap Technical Resource for the appropriate commands, which might be heap.getSessionId() for heap_getSessionId and heap.userId for heap_userId. Confirm with your Heap Technical Resource before saving and pushing the draft live. Test the new functionality by clicking on the Test button in your draft tag by adding your website URL with ?invoca_rev=draft at the end of your URL and call the phone number on the website to make sure the data was accurately captured.

3. After successfully reading and appending the Heap User ID and Session ID to the call, create a custom webhook to transmit this data to Heap.

   • Navigate to "Integrations" on the left-side panel.
   • Select "Custom Webhooks."
   • Click on the green button labeled "New Webhook."
   • Choose the "Post-Call" Webhook.
   • Name your webhook descriptively, such as "Heap."
   • Ensure the URL has POST selected and add the URL endpoint from the Track (server-side) API to the URL input line.
   • Update the Content-Type to "JSON" and add your JSON body Request to this section.
   • For dynamic value passing, click on "Add Substitute Parameter <>" as the JSON body value.
   • Go to the "Firing Conditions" tab and under "Fire On," select "All call-related transactions."
   • Save your configurations.

4. Test the functionality by navigating to your website, calling an Invoca number, and confirming that the Heap IDs are captured and passed through the new custom webhook.

Cause

Integrate Invoca Call Data and Signals with Heap seamlessly by leveraging the Invoca Custom Webhook feature. Explore the capabilities of the Track (server-side) API for a streamlined connection: Heap Track API Reference.

Additional Information

• The Track (server-side) API doesn't inherently support the inclusion of user_id and session_id. Clients are advised to collaborate with their Heap Technical/Developer Resource to customize their Heap platform, enabling it to accept two supplementary parameters in the Track server-side API.
• The Track (server-side) API uses ISO8601 datetime format, which, unfortunately, is not supported by the Invoca webhook. However, the Track (server-side) API defaults to the current time if this parameter is omitted in the request. It is strongly recommended to refrain from passing this parameter to ensure optimal functionality.