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.
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
- Sign in to your Vidyard account
- 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
- Next to Analytics Webhooks, select Add
- 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.
- Select the types of data you want to subscribe to (see Event Subscriptions)
- 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.
- Select Admin > Integrations from the main menu
- 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:
Optionally, if you use Postman to manage APIs, you can use the following link to import a collection for Vidyard’s Analytics Webhooks:
Create a new subscription
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).
A successful request receives a response with the webhook ID. You’ll need
webhook_id to make PUT and DELETE requests.
Return all existing subscriptions
Use the following call to retrieve a list of all subscriptions associated with your API token.
A successful request returns the following details about existing webhooks:
Update or delete a subscription
Make changes to any value in the request body to update the subscription (
To delete a subscription, make the following call:
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 (
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).
"player_name":"Video Marketing Handbook",
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.
"player_name": "Video Marketing Handbook",
"video_name": "Marketing 101",
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.
Glossary of terms
|Attribute key||Event type||Description|
|account_id||All types||The unique ID of the top-level folder in the Vidyard account where the data was sent from|
|embed_url||Percent watched||The URL where the video is embedded/watched. UTM values are respected, but any other query strings are stripped from the payload.|
|attention_span||Attention span||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.
The value for each segment of the array indicates how many times the viewer watched the segment.
|day||Attention span||The date that a particular set of `attention_span` data was calculated.|
|organization_id||All types||The ID of the folder in Vidyard where the webhook is set up.
Note: since the webhook can pass video data from subfolders, this ID may not necessarily represent the folder where the video is located.
|organization_name||All types||The name of the folder where the webhook is set up.|
|percent_watched||Percent watched, Identified view||An integer value that represents the amount of the video a person has watched, expressed as a percentage.
This value is not dependent on having watched a specific point in the video. For example, watching the first 10%, then skipping ahead to watch another 15% will trigger the 0 and 25 messages.
|player_organization_id||Percent watched, Identified view||The unique ID of the folder where the video is located in Vidyard|
|player_uuid||All types||The unique ID of the video player|
|player_name||All types||The name of the video player (typically the same as the `video_name`)|
|player_load_id||All types||The unique ID assigned to the video player when it loads. Changes in this value indicate a new browser session or page refresh.|
|player_load_metadata||All types||Any custom data that you pass through to the webhook payload using the vydata parameter|
|request_id||All types||A unique ID assigned to the payload of webhook data. Duplication of this value indicates that the data has already been sent.|
|timestamp||All types||The time and date that the video view occurred|
|type||All types||Indicates the type of data sent from the webhook (`view`, `attention_span`, `identified_view`)|
|video_id||All types||The unique ID of the video|
|video_name||All types||The name of the video that was watched (may differ from player name if the video is included in a playlist).|
|visitor_vidyard_uuid||All types||A unique ID assigned to the viewer of the video|
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:
With a video embed code:
You can also review our CodePen for an example of how to use a function to set a URI encoded value in the
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.
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
- 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.