Vidyard analytics subscription webhook

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 Add
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 Connect

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.
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.

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'

Pass custom third-party data to your application

In both the percent watched and attention span payloads, custom data can be passed into the player_load_metadata field through use of the vydata parameter.

You might use vydata, for example, to associate third-party information back to vidyard_visitor_uuid and other values from the API.

• The value passed should be provided as a URI encoded JSON string
• Invalid JSON will be returned in the response as undefined
  { undefined: "%7B%22title%22foo%22,%22name%22:%22bar%22%7D" }

vydata on a sharing page URL

share.vidyard.com/watch/[uuid]?vydata="%7B%22title%22:%22foo%22,%22name%22:%22bar%22%7D”

vydata on an embed code

The id on the img tag will need to be added to the Vidyard provided script.

<!DOCTYPE html>
<html>
<head>

<!-- Adding jQuery as one of my calls below uses jQuery. You can modify to use pure JS if you choose. -->
<script src="https://ajax.googleapis.com/ajax/libs/jquery/3.3.1/jquery.min.js"></script>

<!-- Initializing the v4 code -->
<!-- The script tag should live in the head of your page if at all possible and only needs to exist once per page -->
<script type="text/javascript" async src="https://play.vidyard.com/embed/v4.js"></script>
</head>

<body>
  <!-- Put this wherever you would like your player to appear -->
  <!-- replace [UUID] with the UUID of the player you wish to embed -->
  <!-- you can use whichever id you would like, "myplayer" is an example -->  
  <img 
    id="myplayer"
    style="max-width: 100%;"
    class="vidyard-player-embed"
    src="https://play.vidyard.com/[UUID].jpg"
    data-uuid="[UUID]"
    data-v="4"
    data-type="inline"
    data-width="640"
    data-height="360"
    data-vydata=""
  />

<script type="text/javascript">
$('document').ready(function(){

var player = document.getElementById("myplayer");

// set the vydata attribute with the stringified pairs 
player.setAttribute("data-vydata", encodeURIComponent(JSON.stringify({
    Title: "foo",
    Name: "bar"
  })));
// Writing the player object to the console for debugging/verification *Optional*
console.log(player);
});
</script>

</body>
</html>

Example response

{ 
"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": {"title":"foo","name":"bar"}
}

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.
• 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.