Configuring Secure WebHook for Subscription API

Setup steps for your webserver

1 - Ensure that the server which will receive callbacks should be hosted at the callback URL provided by you in the create subscription request.

2. Webhook should support both HEAD and POST request types. 

3 - To validate your webhook's authenticity, InsideView sends a HEAD request with a validation code as a request header "X-InsideViewAPI-ValidationCode". Your server should respond to the HEAD request made by InsideView by sending a response header "X-InsideViewAPI-ValidationCode" echoing the value received in the request header "X-InsideViewAPI-ValidationCode".

Sample Java Code using basic httpServlet :

protected void doHead(HttpServletRequest req, HttpServletResponse resp) throws ServletException, IOException {
System.out.println(req.getHeader("X-InsideViewAPI-ValidationCode")); //This request header is sent by Insideview as a HEAD request to the url which is configured as the webook
resp.setHeader("X-InsideViewAPI-ValidationCode", req.getHeader("X-InsideViewAPI-ValidationCode")); // Echo the header sent by InsideView
}

Note: There might be a delay (a maximum of 2-3 minutes) before InsideView sends the validation request to your callback webserver.

Creating a subscription with a secure webhook

To create a subscription, see [POST] - Create Subscription. If your webserver is ready to respond to validation requests, your request to create a successful subscription should be successful with status of webhook as "VERIFICATION_PENDING".

After submitting a create subscription request initial response will be as follows.

{
  ..., 
 "webhook": {
    "url": "",
    "status": "VERIFICATION_PENDING"
  },
  ...,
  "subscriptionType": "company"
}

Successful webhook validation

If InsideView successfully completes validation of webook then fetch the subscription, see [GET] - Subscription Details. The response will be as follows:

{
  ..., 
 "webhook": {
    "url": "",
    "status": "ACTIVE"
  },
  ...,
  "subscriptionType": "company"
}

Unsuccessful webhook validation

If your webserver is not setup correctly to respond to verification request from InsideView your subscription creation will still be SUCCESSFUL with webhook status DISABLED.

If webhook validation fails then fetch the subscription , see [GET] - Subscription Details. The response will be as follows:

{
  ..., 
    "url": "",
    "status": "DISABLED",
    "disableReasonMessage": "Please echo X-InsideViewAPI-ValidationCode request header value as response header with name X-InsideViewAPI-ValidationCode",
    "disableReasonErrorCode": "400-2101"
      ...,
  "subscriptionType": "company"
}

The response above implies that your webserver did not echo back the header as expected by InsideView.

Webhook validation can fail due to the following errors - 

What happens after Webhook setup is successful?

InsideView generates Alerts for any change in the subscribed entities for all the Subscriptions. If any of the subscriptions have a validated webhook associated with it, then InsideView sends a POST request to the webhook.
This POST call contains the following information in the payload:

Example 
{
"alertId":"364559",
"subscriptionId":"oshbv7671moesavtb0e0",
"date":"2020-02-26 11:52:29:00+0000",
"type":"company"
}

In order to fetch the alert details, use the Fetch Alerts call. 

Verify the Authenticity of InsideView call to the Webhook:

At the time of Subscription Creation or Subscription Update, you can use the signingSecret parameter to establish a secret key between your webhook and Insideview. This Key is used by Insidview to create a header X-InsideViewAPI-AlertDataSignature. The content of this header is the same as payload encrypted by signingSecret via HMAC SHA1 algorithm. You can decrypt this header using the same signingSecret and verify that Payload is the same as decrypted Header content. This established the authenticity of the POST call. 

The X-InsideViewAPI-AlertDataSignature header is sent IF AND ONLY IF the webhook is configured with a signing secret.