Callback webhooks

CallbackEndpointController Documentation

This section documents the endpoints exposed by the CallbackEndpointController for managing callback endpoints. These endpoints allow the creation, update, retrieval, search, and deletion of callback endpoints associated with accounts and sub-accounts.

Base URL

/api/callback

Authorization

Access to all endpoints requires the following authority:

BACKOFFICE

Endpoints

1. Create Callback Endpoint

Method: POST
URL: /api/callback
Authorization: Required

Request Body

{
  "callbackUrl": "https://example.com/callback",
  "authenticationSchema": "CLIENT_CREDENTIALS", // or BASIC
  "clientCredentials": {
    "clientId": "example-client-id",
    "clientSecret": "example-client-secret"
  },
  "basic": {
    "username": "user",
    "password": "pass"
  }
}

Response

{ 
    "id": "uuid", 
    "callbackUrl": "https://example.com/callback", 
    "entityType": "ACCOUNT" 
}

Example cURL

curl --location --request POST '{{BASE-URL}}/api/callback' \ 
--header 'Content-Type: application/json' \ 
--header 'Authorization: Bearer {{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}} 
    } 
}'

2. Update Callback Endpoint

Method: PUT
URL: /api/callback/{uuid}
Authorization: Required

Request Body

Same as "Create Callback Endpoint".

{
  "callbackUrl": "https://example.com/callback",
  "authenticationSchema": "CLIENT_CREDENTIALS", // or BASIC
  "clientCredentials": {
    "clientId": "example-client-id",
    "clientSecret": "example-client-secret"
  },
  "basic": {
    "username": "user",
    "password": "pass"
  }
}

Response

{
  "id": "uuid",
  "callbackUrl": "https://example.com/callback",
  "entityType": "ACCOUNT"
}

Example cURL

curl --location --request PUT '{{BASE-URL}}/api/callback/{{CALLBACK-UUID}}' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {{YOUR-ACCESS-TOKEN}}' \
--data '{
    "callbackUrl": {{CALLBACK-URL}}
}'

3. Get Callback Endpoint by UUID

Method: GET
URL: /api/callback/{uuid}
Authorization: Required

Response

{
  "id": "uuid",
  "callbackUrl": "https://example.com/callback"
}

Example cURL

curl --location --request GET '{{BASE-URL}}/api/callback/{{CALLBACK-UUID}}' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {{YOUR-ACCESS-TOKEN}}' \

4. Search Callback Endpoints

Method: GET
URL: /api/callback/search
Authorization: Required

Query Parameters

Name

Required

Description

accountId

Yes

UUID of the account

Example cURL

curl --location --request GET '{{BASE-URL}}/api/callback/search?accountId={{ACCOUNT_UUID}}' \
--header 'Authorization: Bearer {{YOUR-ACCESS-TOKEN}}'

Response (Paginated)

{
    "content": [
        {
            "id": "09a85e3b-8d49-4209-80e6-53d6fbc02da6",
            "callbackUrl": "https://example.com/callbackSubAccount3",
            "entityType": "ACCOUNT"
        },
        {
            "id": "aff03e0e-9bec-46d8-b4a0-bc30e41ca06e",
            "callbackUrl": "https://example.com/callbackSubAccount",
            "entityType": "ACCOUNT"
        },
        {
            "id": "f15d1165-f977-490a-a938-f027c6cb7157",
            "callbackUrl": "https://example.com/callbackSubAccount453",
            "entityType": "ACCOUNT"
        },
        {
            "id": "f6169a81-0653-460e-aa13-26cd4e4074e0",
            "callbackUrl": "https://example.com/callbackSubAccount43",
            "entityType": "ACCOUNT"
        },
        {
            "id": "febf49a1-1225-4d35-b04c-641a5009db01",
            "callbackUrl": "https://example.com/callback",
            "entityType": "ACCOUNT"
        }
    ],
    "pageable": {
        "pageNumber": 0,
        "pageSize": 20,
        "sort": {
            "unsorted": true,
            "sorted": false,
            "empty": true
        },
        "offset": 0,
        "paged": true,
        "unpaged": false
    },
    "totalElements": 5,
    "totalPages": 1,
    "last": true,
    "numberOfElements": 5,
    "size": 20,
    "number": 0,
    "sort": {
        "unsorted": true,
        "sorted": false,
        "empty": true
    },
    "first": true,
    "empty": false
}

5. Delete Callback Endpoints

Method: DELETE
URL: /api/callback/{id}
Authorization: Required

Description: Deletes a callback endpoint by its UUID.

Response:

HTTP 204 No Content on successful deletion.

Example cURL

curl --location --request DELETE '{{BASE-URL}}/api/callback/{{CALLBACK-UUID}}' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {{YOUR-ACCESS-TOKEN}}'

Register new callback endpoint

The SDK can notify registered endpoints about video events, such as video open times, viewing length, and more.

To start receiving webhook notifications, the first step is to register the destination endpoint and the authentication method. The callback resource enables users to register multiple endpoints, facilitating broadcast notifications.

Fields “basic” or “clientCredentials” are required depending on the “authenticationSchema” selected. For example, if Basic Authentication is chosen, the clientCredentials node is not required, and vice versa.

curl --location '{{BASE-URL}}/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}}
    }
}'

Params:

BASE-URL:

Release Candidate (RC): https://sdk-mobile-api-rc.truvideo.com
Production: https://sdk-mobile-api.truvideo.com

YOUR-ACCESS-TOKEN:

Access token provided by the endpoint mentioned on this documentation: [SDK Mobile] - Generate an API Token

CALLBACK-URL: Callback Url provided by the Partner. Example: "https://webhook.site/908d2965-d127-4527-865b-7ca179b872d6"

AUTHENTICATION-SCHEMA: These are the values:

NONE: Without authentication
CLIENT_CREDENTIALS: Token authentication
BASIC: User and Password authentication.

GET-ACCESS-TOKEN-URL: URL to get then access token when the authorization is implemented using OAuth2 (Client credentials flow). Optional.

TOKEN-SCOPE: Permissions requested by the client to access protected resources like write, read, etc. Optional.

CLIENT-ID: OAuth2 client ID value.

CLIENT-SECRET: OAuth2 client secret value.

USER: Username for basic authentication.

PASSWORD:Password for basic authentication

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.
endlinkHash: Hash corresponding to the endlink
displayCategory: Category of the played mediaId, which can be CONTENT, PREROLL, or POSTROLL

{
    "url": "https://sdk-endlink-ui-rc.truvideo.com/8B5F8B10768042592A4E528F9716391A05019591FC6FE2CC0C3E47DD0FEAA2BF",
}

If, before opening it in the browser, the url receives additional query parameters:

https://sdk-endlink-ui-rc.truvideo.com/8B5F8B10768042592A4E528F9716391A05019591FC6FE2CC0C3E47DD0FEAA2BF?gender=education&lang=en

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

PAYLOAD BY TYPE

URL_INITIATED

MEDIA_VIEW

MEDIA_DURATION

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,
  "endlinkHash": "120B491BD12EB2DCECC52FF42C1C48A467831FCBFEE1ABEC3473D7E0C7721231",
  "displayCategory": "PREROLL"
}

Webhook Example for Video media type

MEDIA_VIEW

{
  "type": "MEDIA_VIEW",
  "payload": [
    {
      "key": "mediaViewingTime",
      "value": "2024-05-27T12:34:56",
      "valueType": "DATE",
      "displayName": "Media Viewing Time"
    }
  ],
  "eventId": "5b915045-0a6d-445a-9340-f614d7f62c16",
  "mediaId": "55dddd20-0020-4a6e-9aea-6721123c3ffd",
  "mediaTags": {
    "key": "val"
  },
  "mediaType": "VIDEO",
  "eventTags": {
    "key": "val"
  },
  "playerTags": {
    "key": "val"
  },
  "mediaCreator": "53b1ad0c-3cd0-4820-92ef-bc9e58c869d0",
  "mediaCreationDate": "2024-07-24T14:27:23",
  "subAccountExternalId": "92f49183-f1ee-4968-968f-fb8a402f9e75",
  "sourceType": "THIRDPARTY_URL_MEDIA",
  "endlinkHash": "120B491BD12EB2DCECC52FF42C1C48A467831FCBFEE1ABEC3473D7E0C7721231",
  "displayCategory": "PREROLL"
}

MEDIA_DURATION

{
  "type": "MEDIA_DURATION",
  "payload": [
    {
      "key": "mediaViewingTime",
      "value": "2024-05-27T12:34:56",
      "valueType": "DATE",
      "displayName": "Media Viewing Time"
    },
    {
      "key": "mediaLength",
      "value": 7200,
      "valueType": "LONG",
      "displayName": "View Length"
    },
    {
      "key": "mediaDuration",
      "value": 108000,
      "valueType": "LONG",
      "displayName": "View Duration"
    }
  ],
  "eventId": "5b915045-0a6d-445a-9340-f614d7f62c16",
  "mediaId": "55dddd20-0020-4a6e-9aea-6721123c3ffd",
  "mediaTags": {
    "key": "val"
  },
  "mediaType": "VIDEO",
  "eventTags": {
    "key": "val"
  },
  "playerTags": {
    "key": "val"
  },
  "mediaCreator": "53b1ad0c-3cd0-4820-92ef-bc9e58c869d0",
  "mediaCreationDate": "2024-07-24T14:27:23",
  "subAccountExternalId": "92f49183-f1ee-4968-968f-fb8a402f9e75",
  "sourceType": "INTERNAL_MEDIA",
  "endlinkHash": "120B491BD12EB2DCECC52FF42C1C48A467831FCBFEE1ABEC3473D7E0C7721231",
  "displayCategory": "PREROLL"
}

Webhook Example for Audio media type

MEDIA_VIEW

{
  "type": "MEDIA_VIEW",
  "payload": [
    {
      "key": "mediaViewingTime",
      "value": "2024-05-27T12:34:56",
      "valueType": "DATE",
      "displayName": "Media Viewing Time"
    }
  ],
  "eventId": "5b915045-0a6d-445a-9340-f614d7f62c16",
  "mediaId": "55dddd20-0020-4a6e-9aea-6721123c3ffd",
  "mediaTags": {
    "key": "val"
  },
  "mediaType": "AUDIO",
  "eventTags": {
    "key": "val"
  },
  "playerTags": {
    "key": "val"
  },
  "mediaCreator": "53b1ad0c-3cd0-4820-92ef-bc9e58c869d0",
  "mediaCreationDate": "2024-07-24T14:27:23",
  "subAccountExternalId": "92f49183-f1ee-4968-968f-fb8a402f9e75",
  "sourceType": "THIRDPARTY_URL_MEDIA",
  "endlinkHash": "120B491BD12EB2DCECC52FF42C1C48A467831FCBFEE1ABEC3473D7E0C7721231",
  "displayCategory": "PREROLL"
}

MEDIA_DURATION

{
  "type": "MEDIA_DURATION",
  "payload": [
    {
      "key": "mediaViewingTime",
      "value": "2024-05-27T12:34:56",
      "valueType": "DATE",
      "displayName": "Media Viewing Time"
    },
    {
      "key": "mediaLength",
      "value": 7200,
      "valueType": "LONG",
      "displayName": "View Length"
    },
    {
      "key": "mediaDuration",
      "value": 108000,
      "valueType": "LONG",
      "displayName": "View Duration"
    }
  ],
  "eventId": "5b915045-0a6d-445a-9340-f614d7f62c16",
  "mediaId": "55dddd20-0020-4a6e-9aea-6721123c3ffd",
  "mediaTags": {
    "key": "val"
  },
  "mediaType": "AUDIO",
  "eventTags": {
    "key": "val"
  },
  "playerTags": {
    "key": "val"
  },
  "mediaCreator": "53b1ad0c-3cd0-4820-92ef-bc9e58c869d0",
  "mediaCreationDate": "2024-07-24T14:27:23",
  "subAccountExternalId": "92f49183-f1ee-4968-968f-fb8a402f9e75",
  "sourceType": "INTERNAL_MEDIA",
  "endlinkHash": "120B491BD12EB2DCECC52FF42C1C48A467831FCBFEE1ABEC3473D7E0C7721231",
  "displayCategory": "PREROLL"
}

Webhook Example for Image media type

MEDIA_VIEW

{
  "type": "MEDIA_VIEW",
  "payload": [
    {
      "key": "mediaViewingTime",
      "value": "2024-05-27T12:34:56",
      "valueType": "DATE",
      "displayName": "Media Viewing Time"
    }
  ],
  "eventId": "5b915045-0a6d-445a-9340-f614d7f62c16",
  "mediaId": "55dddd20-0020-4a6e-9aea-6721123c3ffd",
  "mediaTags": {
    "key": "val"
  },
  "mediaType": "IMAGE",
  "eventTags": {
    "key": "val"
  },
  "playerTags": {
    "key": "val"
  },
  "mediaCreator": "53b1ad0c-3cd0-4820-92ef-bc9e58c869d0",
  "mediaCreationDate": "2024-07-24T14:27:23",
  "subAccountExternalId": "92f49183-f1ee-4968-968f-fb8a402f9e75",
  "sourceType": "THIRDPARTY_URL_MEDIA",
  "endlinkHash": "120B491BD12EB2DCECC52FF42C1C48A467831FCBFEE1ABEC3473D7E0C7721231",
  "displayCategory": "PREROLL"
}

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.

PreviousUpload File NextFetch webhook events

Last updated 2 months ago

CallbackEndpointController Documentation

Base URL

Authorization

Endpoints

1. Create Callback Endpoint

2. Update Callback Endpoint

3. Get Callback Endpoint by UUID

4. Search Callback Endpoints

5. Delete Callback Endpoints

Register new callback endpoint

Media-related events

Webhooks payload

Retry policies

Source type values