How to use the analytics subscription webhook

The analytics webhook allows you to subscribe to and send video data from Vidyard to an external app.

View data from the webhook is delivered to a custom endpoint as HTTP requests in JSON format. You can use the webhook feature in Vidyard to set up and manage the types of data you subscribe to, or you can use the API to make POST, GET PUT and DELETE requests.

Requirements

Depending on how you choose to set the webhook, you require 1 of 2 user permissions.

• Set up a webhook in your Vidyard account → you must belong to a team with the Edit Integrations permission
• Set up a webhook via the API → you must belong to a team with the Edit API Tokens permission to obtain a token

Choose a folder to set up the webhook

The folder where you set up a webhook determines which videos you receive data from when an event or trigger occurs.

• When you sign in to your Vidyard account, you can Change Folders on the integrations page (Admin > Integrations) to set up a webhook at a different level of the folder structure.
  
  
• If you are using the API to set up and manage a webhook, your folder is determined by your API Token.

Any subfolders will inherit the webhook from their immediate parent folder. This behavior allows you to apply the webhook to a group/branch of folders without having to set up the webhook multiple times in separate, individual folders.

In the following example, you can see how the webhook might be set up 2 different ways:

• Webhook #1 is set up and applies to the videos in the Demos folder
• Webhook #2 is set up in the Marketing folder. As a result, it also applies to the videos in the August and July Campaign subfolders

Set up and manage a webhook in Vidyard

1. Sign in to your Vidyard account
2. Select Admin > Integrations from the main menu
   • If needed, select Change Folder to switch into the folder where you want to set up the webhook
3. Next to Analytics Webhooks, select Add
4. Enter the endpoint URL of the application you want to send data to, plus a Security Key
   • The security key is a shared secret used to validate that the data sent to your application actually came from Vidyard. Refer to the logs in your endpoint to verify that requests return the correct security key.
5. Select the types of data you want to subscribe to (see Event Subscriptions)
6. Select Connect

Manage existing webhooks in Vidyard

Once you have a webhook(s) set up, you can select Manage to update your endpoint, security key or data subscriptions; delete a webhook; or add further webhook endpoints to receive data.

1. Select Admin > Integrations from the main menu
2. Select Manage next to Analytics Webhooks

Set up and manage a webhook via API

When you set up and manage webhook subscriptions through the API, always include your API token in the header of your requests. The header should also include:

Accept: application/json
Content-Type: application/json

Optionally, if you use Postman to manage APIs, you can use the following link to import a collection for Vidyard’s Analytics Webhooks:

https://vy-docs.s3.amazonaws.com/postman/VidyardAnalyticsWebhooks.postman_collection.json

Create a new subscription

POST https://analytics-api.vidyard.com/v1/integrations/webhooks

In the request body, use url to specify the receiving application’s endpoint. Use security_key to define a shared secret that you can use to validate requests. Use event_subscriptions to specify the data that you want to subscribe to (learn more about event subscriptions).

{
  "url": "{{webhook_url}}",
  "security_key": "yourKey",
  "event_subscriptions": [
  "view",
  "attention_span",
  "identified_view"
]
}

A successful request receives a response with the webhook ID. You’ll need webhook_id to make PUT and DELETE requests.

{
  "webhook_id": 123456
}

Return all existing subscriptions

Use the following call to retrieve a list of all subscriptions associated with your API token.

GET https://analytics-api.vidyard.com/v1/integrations/webhooks

A successful request returns the following details about existing webhooks:

{
  "id": 123456,
  "url": "{{webhook_url}}",
  "security_key": "yourKey",
  "is_valid": true,
  "event_subscriptions": [
  "view",
  "attention_span",
  "identified_view"
]
},

Update or delete a subscription

PUT https://analytics-api.vidyard.com/v1/integrations/webhooks/{{WEBHOOK_ID}}

Make changes to any value in the request body to update the subscription (url, security_key or event_subscriptions)

To delete a subscription, make the following call:

DELETE https://analytics-api.vidyard.com/v1/integrations/webhooks/{{WEBHOOK_ID}}

Event subscriptions and payloads

There are 3 types of data you can use the webhook to subscribe to:

• Percent watched
• Attention span
• Identified view

Percent watched

Percent watched (view) represents the amount of the video that a person watched, expressed as percent-based milestones (0, 25, 50, 75, 100). If a person watched 100% of a video, you should receive 5 separate payloads (one for each milestone).

{
  "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"
}

Attention span

attention_span represents the number of times a unique viewer watches each second of a video on a particular day.

attention_span returns an array representing up to the first 200 seconds of the video. If the video is longer than 200 seconds, the array represents the timeline of the video broken up into 200 equal segments.

In the payload, day indicates the date that a particular set 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,
  "account_id": "123456"
}

Identified view

identified_view represents a video view that you were able to associate with a viewer’s email address (learn more about how to identify viewers).

The webhook for this event gets queued when the video starts to play. The payload only fires once a duration equal to the total length of the video passes.

For example, if a viewer starts a 10-second long video and pauses the video at 6 seconds, the webhook will fire the payload 4 seconds later (after a total of 10 seconds has passed). As a result, the percent_watched value will indicate that the viewer watched 60% of the video.

The payload for this event only fires once, and only after Vidyard calculates how much of the video has been watched. The event does not rerun if the viewer pauses and continues the video minutes later, nor does it rerun on subsequent views within the same session.

{
  "type":"identified_view",
  "timestamp":"2023-03-02T19:00:35Z",
  "request_id":"fe65dcaa-ecee-43dc-8dda-e064ce5ffbcd",
  "visitor_vidyard_uuid":"iaUEYUaowjXgDFu4vVr_vw",
  "organization_id":"508957",
  "organization_name":"Parent Folder",
  "account_id":"508957",
  "player_uuid":"zufV4qiq4HnatsvtWsWKDN",
  "player_name":"Yukon",
  "video_id":"12524298",
  "video_name": "Yukon",
  "embed_url":"https://share.vidyard.com/watch/zufV4qiq4HnatsvtWsWKDN",
  "percent_watched":100.0,
  "player_load_id":"5861614547",
  "player_load_metadata":{},
  "player_organization_id": "123456"
  "email":"brendan.odriscoll+123@vidyard.com"
}

Glossary of terms

Pass custom data in webhook payloads

You can use a vydata query parameter with a video sharing link or embed code to pass custom data into the player_load_metadata attribute of any webhook payload.

The value that you pass should be provided as a URI encoded JSON string. For example, if you want to pass the JSON string “key:value” as custom data, it would look as follows:

With a video sharing link:

share.vidyard.com/watch/[uuid]?vydata=%7B%22key%22%3A%22value%22%7D

With a video embed code:

<head>
<script type="text/javascript" async src="https://play.vidyard.com/embed/v4.js"></script>
</head>

<body>
<img>
  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="%7B%22key%22%3A%22value%22%7D"
/>
</body>

You can also review our CodePen for an example of how to use a function to set a URI encoded value in the vydata parameter.

Handling webhook responses

• Security key validation: to ensure that the requests that you receive from the webhook are actually coming from Vidyard, we populate the header of each payload with `x-vy-security-key`. This value is defined in the body of the POST message that you used to create the webhook. Use the security header to validate the authenticity of each payload.
  
  
• Note on order: 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 in each payload to verify when data was received.

Retries

If your service has problems handling notifications at any time, we will attempt to resend the failed notifications. We will retry in the following cases:

• Connection failed
• Timeout
• Error codes – if your service responses with an HTTP status code (4xx or 5xx)

For the Percent Watched and Attention Span subscriptions, we will retry up to 25 times over a period of 24-30 days.

For the Identified View subscription, we will retry 3 times over a period of 1-1.5 minutes.