Webhooks API
Contents
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 |
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
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
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
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
