Webhooks

A webhook is a way in which client applications can receieve  http callbacks when certain events occur. A web application implementing webhooks will POST a message to a URL when something happens. When a web application enables users to register their own URLs, the users can then extend, customize, and integrate that application with their own custom extensions or even with other applications around the web. For the user, webhooks are a way to receive valuable information when it happens, rather than continually polling for that data and receiving nothing valuable most of the time.

Using Webhooks in VerticalResponse

VR provides a way for your client application to create and maintain its own hook subscriptions through a REST API. Webhooks can be created in VerticalResponse using an API .

Every time you use VerticalResponse’s Webhooks API to create, update, delete or list the webhooks you have created, you will need to use the client id and access token just as you would for any other VR API. You can use the same VR user for multiple client applications, as long as that user has authorized those applications. Typically you will use your own VR account details for registering hooks.

Note:  Keep in mind that hook subscriptions are defined per client and not per user.

Events

VR Webhooks implementation supports the following three events.

Contact Create

Whenever a new contact is created in VerticalResponse for a given user , a POST call to the endpoint registered by the client application will be triggered.

Contact Unsubscribe

Whenever a contact unsubscribes from a VerticalResponse account,  a POST call to the endpoint registered by the client application will be triggered.

Uploading a list of contacts

Whenever a list of contacts is uploaded to VerticalResponse,  a POST call to the endpoint registered by the client application will be triggered.

Receiving Webhooks

The URL that is used to register for callback is basically an endpoint in your webserver that can receive POST requests. The responsibility of the hook target is to record the events that it receives, and quickly return a response. If you think that actually processing the events received will take a lot of time, you should just record the event and process it later with an asynchronous background task. You can return 200 or 202 responses when you receive a POST call,however the content and status code of the response are ignored. So the less information returned the less overhead to your server. Don't return 3xx redirect responses, since we don't follow them.

If you would like to have additional security to make sure the calls coming to your server are indeed from VR, you can provide a secret key when you register a Webhook.The events we post include a Content-HMAC header. This header serves three purposes: verifying who we are, verifying that the events you receive are meant for you, and verifying the data itself. For more refer the API docs

Sample Response Callback

In case of a contact create webhook, the POST callback to the target server will be as below. Note that the user_id is passed. This is to indicate that "contact.create" event took place for this user_id. Also the URL of the contact created is passed along. To get more details about this contact, another API call should be made.

For more details on the response, check the API Docs.

Failed Callbacks

If you have server outages we don't try to repost the events you missed.  If you know you had a server outage, you may just want to refresh your data from the API, especially if last_event_at doesn't match what you expect. If you know you're going to have a scheduled server outage, for maintenance, it would be better to set the hook subscription to inactive until the server is back up - it will cut down on network overhead.

No Confidential Information

We don't send any confidential data in an event. No user or contact information, no email addresses. For most event types, we only send the user_id, the id(s) of the affected resource(s), and the VR API URL of the associated resource. To get more details you can follow the URL of the returned resource with the right client_id and access_token. The benefit of these restrictions is that you don't have to worry about keeping the data in the events we post a secret. Your hook target service can even be HTTP, though we do recommend HTTPS in general. For that matter, your hook subscriptions can point to third-party services without worrying about confidentiality (with permission from those third-parties though). No one will be able to see your confidential data without logging into the VR API.

Best Practices:

1. Only act on the event when you receive it the first time.Every event VR posts has a unique event_at timestamp . This will help prevent against any replay attack of any kind.

2. If you receive events with the same event_at more than once, especially of the same event_type and for the same user_id, then only record them the first time you receive them; don't bother to record them again. Don't return an error status; this is considered something that may happen by accident , most likely due to network weirdness, and we don't pay attention to the response status anyway.

3. VR's callback return an events array. Events in the events array can belong to different users. This is the reason the user_id is in the event object, rather than an attribute of the overall collection like the client_id.Don't assume that the events in one post all happened after the events that you received in previous posts. There are many reasons why you may receive events out of order, even for events that we posted in order - network speed variance, for instance.