Webhooks API

Contents

Overview

Create Webhook

Update Webhook

Delete Webhook

Overview

Webhooks tell you that something happened, so you don't have to poll our API's periodically and see what changed. We consider these changes as events. With VR’s webhooks, the client application can subscribe to the following events

Hook Name Description
New Contact Create Trigger a POST callback whenever a new contact is created
Contact Unsusbcribe Triggers a POST callback whenever a contact has unsubscribed from the user's mailing lists
Uploading a list of contacts Triggers when a list of contacts has been uploaded

Create Webhook API

VR allows you to create webhooks using an API. Like all other API calls, this also requires an access token. Since the client application or the developer will be creating these webhooks, the developer's test account can be used to create the webhooks API. In addition to specifying what type of event the client application will subscribe to, the webhooks create API also requires the following attributes

Field Name Description Rules
url The URL that will accept the POST requests with the event data. Required for a hook subscription. Unique per client.
event_types An array of allowed event types, in strings , separated by commas.One or more event types is required for a hook subscription. Supported event types are contact.create, contact.unsubscribe, contact.batch.import optional
secret Can be used to make sure that VR is calling the end point.null by default optional
is_active Determines whether the hook subscription is "active" or not. Only active hook subsrcriptions will receive a callback. Active by default optional

URL

We only support HTTP or HTTPS URLs. If the URL includes a fragment (the part starting with the # character) then the fragment will be removed. If the URL includes a query (the part starting with the ? character) then that will be retained. We don't support Basic Auth yet, so don't include user and password parts in the URL. We don't accept more than one hook subscription to the same URL for the same client application. URLs with the same server, protocol and path, but different query parts, are considered different.

 

Secret

The secret key is a Base64-encoded binary in a string. Use strict Base64 encoding, no newlines, and not the URL-safe variant encoding. After it is decoded, the key must be at least 20 bytes; if it is more than 64 bytes, a SHA1 checksum of the key will be used as the key instead. A key containing only spaces and/or null bytes will not be accepted.If the key is not provided in strict Base64 format then we will assume that you accidentally forgot to Base64 encode the string. We will convert the string to UTF-8 encoding, then use the resulting binary data as the key. The byte length and space/null restrictions will apply to the resulting key. If you don't provide a secret key on create, or if you provide a null value as a secret key on create or update, then we don't include the Content-HMAC header in posts to this hook target. You must make your create or update requests in JSON format to be able to provide a null value as a parameter though; URL or form encoded requests don't support null values, and an empty string is not treated as equivalent to a null.

 

is_active

A hook subscription is active by default on hook creation. A hook can be made inactive by setting the is_active parameter to false. When a hook is false, no callbacks are made to it.This can be useful if you want to temporarily stop getting events posted to that server, but don't want to lose the subscription entirely. Inactive hook subscriptions still count when considering whether a particular URL has been subscribed already.

Sample Request

 

Update Webhook API

The attributes of a hook like URL, is_active , event_types and secret can be changed by using the update hook API

URL

https://vrapi.verticalresponse.com/api/v1/hooks/hook_id

Method

 PUT

Sample Request

List Webhooks

This API will list all the webhooks that a particular client_id has subscribed to.

URL

https://vrapi.verticalresponse.com/api/v1/hooks/hook_id

Method

 GET

Sample Request

Sample Response

Delete Webhook

If the client does not require a webhook or an event subscription , they can delete the webhook. On deletion, the client will not get event notifications when the particular event occurs. Also by deleting a webhook, the URL can be used again to create a new hook.If the client wants to only temporarily turn off notifications, the UPDATE API can be used and the is_active flag can be set to false.

URL

https://vrapi.verticalresponse.com/api/v1/hooks/hook_id

Method

 DELETE

Sample Request

Sample Response