Callback webhook
Deprication Warning
This document is archived and will be maintained only until September 15. Please refer to the latest documentation here for updated information.
Register new callback endpoint
To begin receiving webhook notifications for video events, such as video open times and viewing durations, you first need to register your destination endpoint and specify the authentication method. The callback resource allows users to register multiple endpoints, enabling broadcast notifications.
The only authentication scheme currently allowed is “NONE.” In upcoming releases, Basic and Client Credentials authentication will also be supported.
Base Url
Release Candidate (RC)
Endpoint - /api/callback
Method -POST
Header -
Content-Type: application/json
Authentication': "${YOUR-ACCESS-TOKEN}
Body -
{
"callbackUrl": {{CALLBACK-URL}},
"authenticationSchema": {{AUTHENTICATION-SCHEMA}},
"basic": {
"user": {{USERNAME}},
"password": {{PASSWORD}}
}
"clientCredentials": {
"tokenUrl": {{GET-ACCESS-TOKEN-URL}},
"scope": {{TOKEN-SCOPE}},
"clientId:" {{CLIENT-ID}},
"clientSecret": {{CLIENT-SECRET}}
}
}Curl Example
curl --location 'https://sdk-mobile-api.truvideo.com/api/callback' \
--header 'Content-Type: application/json' \
--header 'Authentication': "${YOUR-ACCESS-TOKEN}" \
--data '{
"callbackUrl": {{CALLBACK-URL}},
"authenticationSchema": {{AUTHENTICATION-SCHEMA}},
"basic": {
"user": {{USERNAME}},
"password": {{PASSWORD}}
}
"clientCredentials": {
"tokenUrl": {{GET-ACCESS-TOKEN-URL}},
"scope": {{TOKEN-SCOPE}},
"clientId:" {{CLIENT-ID}},
"clientSecret": {{CLIENT-SECRET}}
}
}'Media-related events
The application triggers webhooks whenever one of the following media-related events occurs:
URL_INITIATED: The user opens the URL of a media.
MEDIA_VIEW: The user starts playing a media.
MEDIA_DURATION: This event is triggered during media playback, indicating the viewing length.
Webhooks payload
The webhook payload contains the following attributes:
mediaId: The ID of the media reproduced.
mediaCreator: The media creator name.
eventId: UUID of the event triggered.
type: Event type (
URL_INITIATED,MEDIA_VIEW,MEDIA_DURATION).mediaType: Whether the media is an image or video (
IMAGE,VIDEO, AUDIO).mediaCreationDate: Media creation date in UTC-0 format (24 hours format).
subAccountExternalId: Subaccount external identifier.
mediaTags: List of media tag values. These values are directly associated with the media and they are provided during the media creation process. The curl of external media creation endpoint accepts a tags field (key-value pairs), which are the same values used to populate this field during the event notification.
playerTags: List of tag values associated to the endlink creation. These values are the ones specified in the endlink creation endpoint.
eventTags: List of event tags values. These are optional tags that can be appended to the endlink URL. Once the endlink endpoint is generated, any query parameters appended to this URL will be interpreted as event tags. For example, given the following endlink.
{
"url": "https://sdk-endlink-ui.truvideo.com/8B5F8B10768042592A4E528F9716391A05019591FC6FE2CC0C3E47DD0FEAA2BF",
}If, before opening it in the browser, the url receives additional query parameters:
https://sdk-endlink-ui.truvideo.com/8B5F8B10768042592A4E528F9716391A05019591FC6FE2CC0C3E47DD0FEAA2BF?gender=education&lang=enThese appended query params will be reported as eventTags as follows:
"eventTags": {
"gender": "education",
"lang": "en"
}sourceType: The source through which the video was generated.
payload: Analytics values related to each event. It depends on each event type and they are mediaViewingTime (timestamp of the event creation), mediaLength (the duration the customer watched the video in seconds) and mediaDuration (video total duration).
key: media analytic name.
value: media analytic value.
valueType: value type (
STRING,BOOLEAN,LONG,INT).displayName: Descriptive label about the value.
URL_INITIATED
MEDIA_VIEW
MEDIA_DURATION
mediaViewingTime
mediaViewingTime
mediaLength
-
-
mediaViewingTime
-
-
mediaDuration
Examples:
URL_INITIATED (applies for all media types)
{
"type": "URL_INITIATED",
"payload": [
{
"key": "mediaViewingTime",
"value": "2024-05-27T12:34:56",
"valueType": "DATE",
"displayName": "Media Viewing Time"
}
],
"eventId": "5b915045-0a6d-445a-9340-f614d7f62c16",
"mediaId": null,
"mediaTags": null,
"mediaType": null,
"eventTags": {
"key": "val"
},
"playerTags": {
"key": "val"
},
"mediaCreator": null,
"mediaCreationDate": "2024-07-24T14:27:23",
"subAccountExternalId": "92f49183-f1ee-4968-968f-fb8a402f9e75",
"sourceType": null
}Video
Audio
Image
Retry policies
When there is an error delivering the webhook message, there will be three additional delivery attempts. Between each attempt, there is a delay of ten seconds, plus an extra delta time. This policy provides the target server with time to recover after a failure.
Source type values
THIRDPARTY_UPLOAD_MEDIA: The media was created from an external file upload to the video platform.
THIRDPARTY_URL_MEDIA: The media was created from an external url video or image.
INTERNAL_MEDIA: Media created from the mobile application.
Last updated
Was this helpful?