Articles in this section

Vidyard analytics subscription webhook

Avatar
Brendan O'Driscoll
  • Updated

Webhooks are automated notifications sent from one app to another whenever a subscribed event occurs. With the Vidyard analytics webhook, you can enable a third-party application to subscribe to view data from videos in your account.

View data is delivered to a custom endpoint as an HTTP POST request in JSON format.

Requirements

  • You must have the Webhooks feature enabled as part of your paid plan with Vidyard

Event subscriptions

There are two types of video view data: attention span and percent watched. You can add multiple endpoints that subscribe to one or both types of data.

Attention span

  • attention_span represents the number of times a unique viewer watches each second of a video on a particular day
  • attention_span will be at most 200 points. If the video is less than 200 seconds it will contain less than 200 points. If the video is greater than 200 seconds it will contain 200 points evenly distributed over the video length.
  • day represents the day on a particular return of attention_span data was calculated.
{
  "type": "attention_span",
  "request_id": "6c4c01671eba-d39a-f894-cea9-6a954935",
  "visitor_vidyard_uuid": "AlfRvTB-4Qtb5sGwYge24z",
  "organization_id": "09891232",
  "organization_name": "Vidyard",
  "player_uuid": "AS0glGQl8eJzmehQFcx4g2",
  "player_name": "Video Marketing Handbook",
  "video_id": "9246580",
  "video_name": "Marketing 101",
  "attention_span": {
    "0": 1,
    "1": 1,
    "2": 1,
    "3": 1,
    "4": 1,
    "5": 1,
...
    "25": 1,
  },
  "day": "2018-08-15T00:00:00Z",
  "timestamp": "2018-08-15T17:21:19Z",
  "player_load_id": 03988869690,
  "player_load_metadata": null
} 

Percent watched

  • percent_watched indicates the percentage that a video has been viewed (represented as milestone data: 0, 25, 50, 75, 100). For example, if someone watches 100% of a video, the subscribing application will receive 5 milestone posts.
{
"type":"view",
"timestamp":"2017-05-15T15:01:29Z",
"request_id":"wdcij9283849fkcwicd096",
"visitor_vidyard_uuid":"qd728596cqc87vdlmjd98b",
"organization_id":"6871",
"organization_name":"Vidyard",
"player_uuid":"osjvn98e78908vidnms893",
"player_name":"Video Marketing Handbook",
"video_id":"924658",
"video_name":"Marketing 101",
"percent_watched":75,
"player_load_id":"517982",
"player_load_metadata": null
}

Add an analytics webhook in Vidyard

Prerequisite:
To manage webhooks in Vidyard, you must belong to a team that has the Edit Integrations permission enabled for each of the folders that you want to subscribe to.

When you add an analytics webhook to your account, you subscribe to view data from videos within a specific folder. If you want to subscribe to view data from videos across the entire account, add the webhook at the parent folder in your account.

You can add more than one subscription webhook to a folder.

  1. From the Vidyard dashboard, select Admin > Integrations
  2. If applicable, click on Change Folder and select the folder that contains the videos that you want to subscribe to.
  3. Next to Analytics Webhooks, select AddAdding a new webhook to a folder in Vidyard
  4. Enter the endpoint URL of your application and a security key
    • The security key is a shared secret used to validate that the data sent to your application was delivered by Vidyard and not another third-party. Refer to the logs in your endpoint to verify requests return the correct security key.
  5. Select the types of data you want to subscribe to
  6. Select ConnectEntering your endpoint URL, security key, and selecting the data you want to subscribe to

Manage an analytics webhook with HTTP requests

You can also create and manage analytics webhooks with HTTP requests through common API tools like Postman or your computer's command terminal.

Make HTTP requests with Postman

To get started, import the subscription webhook collection into Postman: https://vy-docs.s3.amazonaws.com/postman/VidyardAnalyticsWebhooks.postman_collection.json

  1. Open the menu next to the collection, then select Edit > Variables.
  2. Under the current value column, replace the AUTH_TOKEN with your Vidyard API token.
  3. Replace the WEBHOOK_URL with the endpoint for your application.Updating the variables for the imported subscription webhook collection in Postman
  4. Make a POST request to create a new webhook. 
    • Indicate a security key in the body of the request. The security key allows you to validate that data from webhook payloads is being delivered from Vidyard and not another third-party.
    • You'll also want to specify the type of data you want to subscribe to—attention span ("attention_span"), percent watched ("view"), or both. Indicate these data types as values in event_subscriptions property.

Making a POST request in Postman to create a new webhook

A successful POST request will return a webhook ID. Make sure to update the WEBHOOK_ID variable in the collection with the returned value. You'll need the ID to make subsequent PUT or DELETE requests.

You can always make a GET request to return active webhooks and their IDs.

Make HTTP requests from your terminal

When making requests from your terminal, always include your API token in the header of your requests.

In the initial POST request, make sure to include in the body:

  • Your application endpoint as the "url" value
  • A value for security_key
  • The events you want to subscribe to: attention_span, view, or both.

A successful POST request will return a webhook_id in the response. You'll need the ID to make PUT and DELETE requests.

POST requests

Creates a webhook for the provided endpoint.

curl -X POST \
 https://analytics-api.vidyard.com/v1/integrations/webhooks \
 -H 'Accept: application/json' \
 -H 'Authorization: Bearer test-token' \
 -H 'Content-Type: application/json' \
 -H 'cache-control: no-cache' \
 -d '{
 "url": "https://example-webhook.com",
 "security_key": "testkey",
 "event_subscriptions": [
 "view",
 "attention_span"
 ]
}'

GET requests

Returns all webbooks from a specific endpoint.

curl -X GET \
 https://analytics-api.vidyard.com/v1/integrations/webhooks \
 -H 'Accept: application/json' \
 -H 'Authorization: Bearer test-token' \
 -H 'cache-control: no-cache'

PUT requests

Change the body of the request to update an existing webhook.

curl -X PUT \
 https://analytics-api.vidyard.com/v1/integrations/webhooks/123 \
 -H 'Accept: application/json' \
 -H 'Authorization: Bearer test-token' \
 -H 'Content-Type: application/json' \
 -H 'cache-control: no-cache' \
 -d '{
"url": "https://example-webhook.com",
"security_key": "testkey", 
"event_subscriptions": ["view"]
}'

Delete a webhook 

Leave body of request empty when deleting a webhook.

curl -X DELETE \
 https://analytics-api.vidyard.com/v1/integrations/webhooks/123 \
 -H 'Accept: application/json' \
 -H 'Authorization: Bearer test-token' \
 -H 'Content-Type: application/json' \
 -H 'cache-control: no-cache'

Handling webhook responses

  • Validate security key: Each payload sent to your endpoint will include the security_key value that you submitted as part of the initial POST request to create the webhook. Look for X-VY-Security-Key:"yourSecurityKey" in the header to validate that the payload came from Vidyard.
  • Order of receipts: The order in which each payload is received may not match the order in which the webhook requests were made. Refer to the timestamp value included in each return to verify when data was received.A payload response from the webhook, including the value submitted for your security key in the header, and a timestamp value included in the body
  • Failure to deliver data: If an error occurs when the webhook delivers a payload, we will attempt to send the data to the endpoint again at increasingly greater intervals. Attempts to re-send data will continue in this manner for a period of 24 or 30 days.

Related articles