Configuring Secure WebHook for Subscription API

Follow

 

 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 - 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 little 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 please follow this link (https://kb.insideview.com/hc/en-us/articles/210015287--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": "<callbackUrl>",

    "status": "VERIFICATION_PENDING"

  },

  ...,

  "subscriptionType": "company"

}

 

 

Successful webhook validation

If InsideView successfully completes validation of webook then fetch subscription (https://kb.insideview.com/hc/en-us/articles/209297778--GET-Subscription-Details) response will be as follows.

{

  ..., 

 "webhook": {

    "url": "<callbackUrl>",

    "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 subscription (https://kb.insideview.com/hc/en-us/articles/209297778--GET-Subscription-Details) response will be as follows.

{

  ..., 

    "url": "<callbackUrl>",

    "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 - 

 

Webhook unreachable 400-2100
Please echo X-InsideViewAPI-ValidationCode request header value as response header with name X-InsideViewAPI-ValidationCode 400-2101
Invalid X-InsideViewAPI-ValidationCode response header value 400-2102, 400-2103               
Incorrect X-InsideViewAPI-ValidationCode response header value 400-2104

 

Was this article helpful?
0 out of 0 found this helpful
Powered by Zendesk