Webhooks

What Are Webhooks?

Webhooks are a way for events in one system to propagate to another quickly and efficiently. The basic principle behind webhooks can be summarised by the phrase “Don’t call us, well call you”. What that really means is that the user designates where Vinsight posts event details only when they happen, and then an external system handles those events however you see fit. This serves as a more quick and efficient alternative to polling Vinsight for changes in the Vinsight API.

How to set up Webhooks in Vinsight

The webhooks list can be found at https://app.vinsight.net/webhooks. All of the fields need to be populated for the webhook to work correctly and the function of each can be described as the following:

• EntityType: The entity on which the webhook is listening for events on e.g. Contact
• EventType: The type of event the webhook is listening for on the EntityType e.g. created
• Url: The URL where the webhook posts the event, with the EntityType object in the POST request body. The URL should direct to a server that you control so that you can write your code that handles the Vinsight data in the way you desire.
• ContentType: Specifies that format the Vinsight Entity data will be sent in the body e.g. json
• IsEnabled: Determines whether or not the webhook is active and will respond to events

So the first row in the below example can be explained as: When a Contact is created in Vinsight, a POST request will be sent to the URL “https://en1jz5rn62ia3.x.pipedream.net” with the new Contact information being sent in the request body, in the JSON format.

Webhooks can also be created programamatically via the API. You can execute a JSON POST request on the /Webhooks endpoint to create a new Webhook. To update an existing webhook use a PUT request to /Webhooks/<WebhookID> and to delete a webhook use a DELETE request to /Webhooks/<WebhookID>.

Webhook Authentication

A Vinsight webhook will always be accompanied by an authentication hash in the x-signature request header. The webhook data can be authenticated by reconstructing the hash using the webhook secret in the Vinsight user interface as the key, and the request body as the data which is subsequently run through the HMAC SHA256 hashing algorithm. If the constructed hash matches the signature in the request header, then you can assume the data is authentic, direct from Vinsight, and has not been tampered with.

If your application creates Webhooks programatically via the API, you can download the webhook secret via JSON GET request to /Webhooks/Secret.json. Do this while you are setting up your webhooks, and store the secret in your own application to ensure it’s value has not been tampered with since initial setup. Each organisation in Vinsight has their own unique webhook secret.

To test your HMAC SHA256 algorithm is working correctly, you should be able to generate the following signature using this example secret and body:

How to Debug Webhooks – Vinsight

Vinsight keeps a record of Webhooks sent for 30 days. These logs are available underneath the Webhooks List, and contain details about the header and body of each webhook:

How to Debug Webhooks – Request Bin

In webhook development we have found the tool https://requestbin.com/ to be very useful for inspecting the POST requests sent from Vinsight when a webhook is triggered. You may find it useful to confirm whether or not the webhooks are firing in Vinsight correctly, you can also see the shape of the data that Vinsight is sending in addition to the request headers which may be useful in processing. You should be mindful of whatever data you send to an external system so in development you may decide to use a demo Vinsight account to test the webhooks and use fake data at your discretion.

RequestBin works by allocating you a URL that you can send any HTTP request to, which it then logs and allows you to inspect them in real time.

A Contact being created in Vinsight will look something like this in RequestBin:

Vinsight’s Responsibilities

Webhook Secret

It is the responsibility of the Vinsight account holder to keep the webhook secret private to ensure the integrity of the Vinsight webhook data entering an external system. If the webhook secret is known to be compromised a new one can be issued by contacting Vinsight Support.

Changing Interface

Vinsight’s data interface is liable to change over time, however, as much as possible we will try to keep our changes additive so they are non-breaking and backwards compatible.

Integration Into External Systems

Vinsight accepts no responsibility regarding how external systems consume Vinsight webhooks, including the security and data integrity of any data consumed by external systems nor are we obligated to provide technical support for how these external systems beyond the webhook interface working as expected.