How to subscribe to real time signals from Insightarc

Creating a Webhook

Webhooks have been designed with security in mind and are specific to a project.

To create a webhook, the first requirement is to provide a URL parameter. When a project with a webhook experiences a change, the update is fired via an HTTP POST request from Insightarc to the URL provided. The body of the request will be a JSON payload of the signal. The provided URL must be a valid URL during the creation of the webhook. We run a quick HTTP HEAD request on the URL, and if a 200 status code is not returned in the response, the webhook will not be created. Additionally, if your URL contains an invalid SSL certificate, the webhook cannot be created.

Triggering Webhooks

Once the webhook signal is set up, any changes to the signals will trigger an HTTP POST request to the provided endpoint.

Example Webhook Response

  {
        "drop_proba": 0.95  //the probability of the client falling off in the next action, 
        "perfomance": 1.2, // percentage of time spent
        "num_events": 10,
        "num_loops": 2,
        "num_broken_buttons": 1,
        "avg_loops": 2.3,
        "avg_broken_buttons": 1,
        "relevant_events":  //optional attribute, may not be supplied
        [
          {"name" :"name of action or url of the visited page"},
        ]
  }

Webhook Signatures

InsightArc also signs webhook requests, allowing you to verify if they originated from InsightArc. Each webhook trigger contains the HTTP header x-insightarc-signature, which is a base64 digest of an HMAC-SHA1 hash. The hashed content should be the binary representation of the concatenation of the full request body and the URL exactly as it was provided during webhook creation. The key used to sign this text is your webhook secret, which can be found at the project settings dialog -> Webhook tab.

Here is an example code snippet in Node.js for verifying the validity of a request:

const crypto = require("crypto");

function verifyWebhookPayload(request, secret, webhookURL) {
  const payload = JSON.stringify(request.body) + webhookURL;
  const payloadHash = crypto.createHmac("sha1", secret).update(payload).digest("base64");
  const headerHash = request.headers["x-insightarc-signature"];
  return payloadHash == headerHash;
}