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.
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_spanrepresents the number of times a unique viewer watches each second of a video on a particular dayattention_spanwill 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.dayrepresents the day on a particular return ofattention_spandata 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,
"account_id": "123456"
}
Percent watched
percent_watchedindicates 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,
"account_id": "123456",
"embed_url": "http(s)://knowledge.vidyard.com/hc/en-us/",
"player_organization_id": "123456"
}
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.
- From the Vidyard dashboard, select Admin > Integrations
- If applicable, click on Change Folder and select the folder that contains the videos that you want to subscribe to.
- Next to Analytics Webhooks, select Add
- 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.
- Select the types of data you want to subscribe to
- Select Connect
Optional: Manage an analytics webhook with HTTP requests
If you prefer, you can instead 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
- Open the menu next to the collection, then select Edit > Variables.
- Under the current value column, replace the
AUTH_TOKENwith your Vidyard API token. - Replace the
WEBHOOK_URLwith the endpoint for your application.
- 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 inevent_subscriptionsproperty.
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"},
"account_id": "123456",
"embed_url": "http(s)://knowledge.vidyard.com/hc/en-us/",
"player_organization_id": "12345"
}
Handling webhook responses
- Validate security key: Each payload sent to your endpoint will include the
security_keyvalue that you submitted as part of the initial POST request to create the webhook. Look forx-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
timestampvalue 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.