How to Use Webhooks With HEAP Analytics

Updated on April 17, 2019 Download PDFDownload as PDF
Download PDF

Brief Overview

Webhooks (AKA callbacks) allow you to trigger 3rd party APIs and/or add WalkMe Event data into your analytics platform. The webhook is triggered by a designated WalkMe Event, for example, a ShoutOut being displayed. The webhook integrates between WalkMe and your chosen 3rd party platform. 

This article explains how to define webhooks for Heap Analytics.

For a deeper understanding of properties and behavior of HEAP’s Track event, please review the API Documentation and Explanations section below.

Steps for using Track Event Webhooks for HEAP Analytics

Step 1: Open an account or log into HEAP

Step 2: Copy the JavaScript snippet (only required if this is your first time using HEAP)

If you have used HEAP before, then skip to Step 3 below. If not, follow these steps:

  • Use the snippet in the HTML of the website that triggers the event (it should appear before the closing </head> tag);
  • You must trigger the event in order to proceed:

Step 3: Click Settings

Step 4: Click Projects

Step 5: Copy the projects environment ID

  • You will use this ID in the snippet of the webpage and will use it on Insights in order to connect the event to this specific project:

Step 6: Review ‘How to Set Up a Webhook’ article

Step 7: Set up your webhook in Insights using the Wizard

Wizard Step 1: Define event

Required properties
  • The Track Event sent to Heap requires these mandatory properties:
    • app_id — taken from Step 5;
    • identity — An identity, typically corresponding to an existing user;
    • event — The name of the Event.
Steps
  1. Select an Event to send to HEAP;
    • In this example, we are sending data about a Smart Walk-Thru Goal being achieved to HEAP as an Event, but you can do likewise with an Event of your choosing:
  2. Click Advanced to open the list of properties;
  3. Uncheck all properties in the Event;
  4. Check the wm.euid box and rename it “identity”;
  5. Click ADD PROPERTY and name it “app_id”; set its value to be the environment ID that you copied in Step 5 above;
  6. Click ADD PROPERTY and name it “event”; set its value to be the Event Name you chose in Wizard Step 1.1 above.
    • This will be the event name shown in your HEAP Analytics platform.

Wizard Step 2: Set destination

Steps
  1. Write in the Destination Platform Name. This name identifies the destination system (In this case HEAP Analytics):
  2. Set Request Type to POST:

  3. Enter Destination URL: “https://heapanalytics.com/api/track“:
  4. Add Headers Content-Type : application/json:
  • Click TEST
    • This will send the event that you defined in Wizard Step 1 to your destination platform to ensure that a connection successfully made;
      • This is a test event sending generated data to your HEAP Analytics environment.
    • You should see the message: “Tested Successfully!”:

      Pro-Tip: If you don’t see the success message, check if all the mandatory properties are defined properly, per the instructions above.

Step 8: View in HEAP the Event received by WalkMe

Step 8a: In Heap, click Events

Step 8b: Click the relevant event under Custom Events

  • Click on the custom event with the API icon to the left (in this case “Launcher_Clicked”);
  • In the Custom Events section, click on the Event Name you configured in the Wizard;
  • You will see the same test data that was sent to your platform when you clicked on the Test button in Step 7 above:
  • In the dashboard on the right, you will see the Event activity:

API Documentation and Explanations on Track Event by HEAP

Possible Body properties HEAP accepts for Track Event

Proprty Name as HEAP expects to receive it Type Required? Description
app_id string Yes The app_id corresponding to one of your projects.
identity string Yes

End user ID.

An identity, typically corresponding to an existing user.

If no such identity exists, then a new user will be created with that identity. Case-sensitive string, limited to 255 characters.

event string Yes

The name of the event.

Limited to 1024 characters.

identity_type string No

A case-sensitive string that defines what type of identity you are sending to Heap (email, user ID, etc.) and can be any custom string.

When provided, Heap will create a user property namedidentity_type with the value of identity.

This is only needed if you have an advanced multi-type identify implementation.

properties object No

An object with key-value properties you want associated with the event. Each key and property must either be a number or string with fewer than 1024 characters.

Example:

"properties": { "subject": "Welcome to My App!", "variation": "A" }
timestamp string No ISO8601 or unix epoch milliseconds e.g. “2017-03-10T22:21:56+00:00”.
idempotency_key string No A unique ID that will be hashed to Heap’s event ID keyspace, to prevent duplication of events. Subsequent calls with the same idempotency key will not update data.

Read more on HEAP’s API.

Example of a request

curl 

-X POST 

-H "Content-Type: application/json" 

-d '{
"app_id": "11",

"identity": "alice@example.com",

"event": "Send Transactional Email",

"timestamp": "2017-03-10T22:21:56+00:00",

"properties": {

"subject": "Welcome to My App!",

"variation": "A"

}

}' 

https://heapanalytics.com/api/track

Was this article helpful?

Related Articles