Introduction

Notifications in Telestream Cloud

Often when using cloud services, you want to stay on top of things and know what is happening with your jobs and files, so you can react if something goes wrong. Telestream Cloud offer such ability as well and goes little further with multiple notifications delivery options 

Staying up to date 

Each of our services - be it Flip, Timed Text Speech or Quality Control - allows you to be notified on certain events or stages of job processing and has its own set of event types. 

Flip Events

video created - your media file has been uploaded successfully and encoding has started
encoding progress - allows to track progress of a single encoding job
video encoded - all encodings for your media file have been completed
encoding completed - single encoding job for your media file has been completed

Timed Text Speech Events

job created - your source file has been uploaded and transcription has started
job progress - allows to track progress of a transcription job
job complete - transcription has been completed successfully
job error - there was an error when processing transcription job

Quality Control Events

job created - your source file has been uploaded and quality check has started
job progress - allows to track progress of a quality control job
media passed, warning, rejected - returns quality check result depending whether media file passed the check, passed with warnings or was rejected (didn’t meet the requirements)
media cancelled - quality control job was cancelled
media error - quality control job failed due to processing error

Delivery Methods

Telestream Cloud gives you a number of options how to deliver notifications in most convenient way for you.

Telestream Cloud Profiles Pipelining

E-mail

Probably the easiest to set up. Simply enter email address to which Telestream Cloud should send the notifications. You can add multiple email addresses.

Webhook

Provide us with the URL we should send the notifications to, pick the HTTP method and that’s it. Pretty simple as well.

Telestream Cloud Profiles Pipelining

Amazon Simple Notification Service

Telestream Cloud Profiles Pipelining

If you’re already on AWS you may prefer to use their Simple Notifications Service as delivery method. It requires you to do little bit of configuration in the AWS console to provide us with data that’s needed for this method to work.

You will need to use our Account ID to identify our AWS account to be able to use the IAM role created for notifications. Additionally, for increased security of your role we require to enter generated external identifier when creating an AWS role. Please make sure you check “Require external ID” checkbox when creating a role. Without the External ID provided you won’t be able to use SNS notifications with Telestream Cloud.

What we need from you are two pieces of information - Role ARN and SNS Topic ARN. IAM Role is an AWS identity not associated with one user assumable by anyone permitted and has defined permission policies that determine what it can and cannot do in AWS.

Please make sure that role has at least have permissions to publish to specific topic.

A Role ARN (Amazon Resource Name) can be found in AWS Management Console under Services > Administration & Security > IAM > Roles in the navigation pane.

SNS Topic ARN uniquely identifies Simple Notification Service topic that serves as communication channel to send messages and subscribe to notifications. A SNS Topic ARN (Amazon Resource Name) can be found in AWS Management Console under Services > Simple Notification Service > Topics in the navigation pane. 

Google Pub/Sub

Telestream Cloud Profiles Pipelining

For those who prefer Google we are offering integration with their native notifications service as well. In this case you will need our Google account e-mail for identification in Permissions settings to be able to access the topic created for notifications.

When setting up Pub/Sub notifications we need the Project ID and Topic Name from you. Projects are a way to organize your Google Cloud Platform resources and consist of a set of users; a set of APIs; and billing, authentication, and monitoring settings. You can get the Project ID from the projects list available from the top bar in your Google Cloud Console.

Topic name identifies the topic in Google Cloud Platform to which messages are sent by publishers, in this case Telestream Cloud. To get the topic name go to Google Cloud console, to Pub/Sub -> Topics and either copy name of an existing one or create new topic. Make sure you add Telestream Cloud email to the members list in Permissions settings and that it has Pub/Sub Publisher role.

Azure Event Grid 

Telestream Cloud Profiles Pipelining

Last but not least - Microsoft Azure Event Grid. To set it up in Telestream Cloud you will need to enter your Access Key that can be found in Azure Portal in Access Keys section for each service. Simply copy one of the access keys and paste it here.

And just like with AWS and Google you need to specify the Event Topic which provides an endpoint where we will send events. To list of topics is available in Event Grid Topics section in Azure Portal. You can either create a new topic or copy existing Topic Endpoint from overview and paste it here.    

API

We will maintain documentation for API V1 and you will still be able to use it.

Using the REST API directly

If you don’t plan to use one of our SDKs you then you will need the following data to make calls to our API:

API Address: https://api.cloud.telestream.net/notifications/v2.0

subscriptions

Subscriptions define where notifications should be delivered. It is triggered on selected events.

list subscriptions

Code samples

require 'rest-client'
require 'json'

headers = {
  'Accept' => 'application/json',
  'X-Api-Key' => 'API_KEY'
}

result = RestClient.get 'https://api.cloud.telestream.net/notifications/v2.0/subscriptions',
  params: {
  }, headers: headers

p JSON.parse(result)

import requests
headers = {
  'Accept': 'application/json',
  'X-Api-Key': 'API_KEY'
}

r = requests.get('https://api.cloud.telestream.net/notifications/v2.0/subscriptions', params={

}, headers = headers)

print r.json()

URL obj = new URL("https://api.cloud.telestream.net/notifications/v2.0/subscriptions");
HttpURLConnection con = (HttpURLConnection) obj.openConnection();
con.setRequestMethod("GET");
int responseCode = con.getResponseCode();
BufferedReader in = new BufferedReader(
    new InputStreamReader(con.getInputStream()));
String inputLine;
StringBuffer response = new StringBuffer();
while ((inputLine = in.readLine()) != null) {
    response.append(inputLine);
}
in.close();
System.out.println(response.toString());

package main

import (
       "bytes"
       "net/http"
)

func main() {

    headers := map[string][]string{
        "Accept": []string{"application/json"},
        "X-Api-Key": []string{"API_KEY"},

    }

    data := bytes.NewBuffer([]byte{jsonReq})
    req, err := http.NewRequest("GET", "https://api.cloud.telestream.net/notifications/v2.0/subscriptions", data)
    req.Header = headers

    client := &http.Client{}
    resp, err := client.Do(req)
    // ...
}

GET /subscriptions

Parameters


service_type string In query optional Service type (qc, tts, flip)
type string In query optional Subscription type (email, webhook, sns, aeg, pubsub)

Example responses

200 Response

[
  {
    "id": "string",
    "type": "string",
    "topic": {
      "account": "string",
      "service": "string",
      "event": "string",
      "project": "string",
      "factory": "string"
    },
    "params": {
      "addresses": [
        "string"
      ],
      "url": "string",
      "method": "GET",
      "retries": 0,
      "content_type": "application/json",
      "topic_arn": "string",
      "role_arn": "string",
      "topic_endpoint": "string",
      "access_key": "string",
      "project_id": "string",
      "topic_name": "string"
    }
  }
]

401 Response

Responses

Status	Description	Schema
200	OK OK	Inline
401	Unauthorized Not authorized	string

Response Schema

Status Code 200


anonymous [subscription] optional none undefined
» id string optional [read-only] Subscription identifier read-only
» type string required Type of subscription (email, webhook, sns, aeg, pubsub) undefined
» topic object required none undefined
»» account string optional [read-only] Account identifier connected to subscription notification read-only
»» service string required Name of service (qc, flip, tts) undefined
»» event string required Name of the event; Quality Control (media-passed, media-error, media-warning, media-rejected, media-canceled, job-created, job-progress), Flip (video-created, video-encoded, encoding-complete, encoding-progress), Transcription (job-created, job-completed, job-error, job-progress) undefined
»» project string optional (for tts, qc service); Project ID undefined
»» factory string optional (for flip service); Factory ID undefined
» params object required none undefined
»» addresses [string] optional (for email subscription type); E-mail addresses undefined
»» url string optional (for webhook subscription type); Webhook URL undefined
»» method string optional (for webhook subscription type); HTTP method; default: POST (GET, POST) undefined
»» retries integer optional (for webhook subscription type); Number of retries before forgetting the notification; default: 0 undefined
»» content_type string optional (for webhook subscription type); default: application/json (application/json, application/x-www-form-urlencoded) undefined
»» topic_arn string optional (for sns subscription type) identifier of an AWS SNS Topic that events will be posted to. undefined
»» role_arn string optional (for sns subscription type) identifier of an AWS IAM Role that will be used for authorization. undefined
»» topic_endpoint string optional (for aeg subscription type) address of an Azure Event Grid Topic that events will be posted to. undefined
»» access_key string optional (for aeg subscription type) secret access key that authorizes Telestream Cloud to write to an Azure Event Grid Topic. undefined
»» project_id string optional (for pubsub subscription type) id of a Google Cloud project that hosts the topic. undefined
»» topic_name string optional (for pubsub subscription type) name of a Google Cloud Pub/Sub topic to which notifications will be published. undefined

Enumerated Values


method GET
method POST
content_type application/json
content_type application/x-www-form-urlencoded

create subscription

Code samples

require 'rest-client'
require 'json'

headers = {
  'Content-Type' => 'application/json',
  'Accept' => 'application/json',
  'X-Api-Key' => 'API_KEY'
}

result = RestClient.post 'https://api.cloud.telestream.net/notifications/v2.0/subscriptions',
  params: {
  }, headers: headers

p JSON.parse(result)

import requests
headers = {
  'Content-Type': 'application/json',
  'Accept': 'application/json',
  'X-Api-Key': 'API_KEY'
}

r = requests.post('https://api.cloud.telestream.net/notifications/v2.0/subscriptions', params={

}, headers = headers)

print r.json()

URL obj = new URL("https://api.cloud.telestream.net/notifications/v2.0/subscriptions");
HttpURLConnection con = (HttpURLConnection) obj.openConnection();
con.setRequestMethod("POST");
int responseCode = con.getResponseCode();
BufferedReader in = new BufferedReader(
    new InputStreamReader(con.getInputStream()));
String inputLine;
StringBuffer response = new StringBuffer();
while ((inputLine = in.readLine()) != null) {
    response.append(inputLine);
}
in.close();
System.out.println(response.toString());

package main

import (
       "bytes"
       "net/http"
)

func main() {

    headers := map[string][]string{
        "Content-Type": []string{"application/json"},
        "Accept": []string{"application/json"},
        "X-Api-Key": []string{"API_KEY"},

    }

    data := bytes.NewBuffer([]byte{jsonReq})
    req, err := http.NewRequest("POST", "https://api.cloud.telestream.net/notifications/v2.0/subscriptions", data)
    req.Header = headers

    client := &http.Client{}
    resp, err := client.Do(req)
    // ...
}

POST /subscriptions

Create a new subscription

Body parameter

{
  "type": "string",
  "topic": {
    "service": "string",
    "event": "string",
    "project": "string",
    "factory": "string"
  },
  "params": {
    "addresses": [
      "string"
    ],
    "url": "string",
    "method": "GET",
    "retries": 0,
    "content_type": "application/json",
    "topic_arn": "string",
    "role_arn": "string",
    "topic_endpoint": "string",
    "access_key": "string",
    "project_id": "string",
    "topic_name": "string"
  }
}

Parameters


body subscription In body optional none

Example responses

200 Response

{
  "id": "string",
  "type": "string",
  "topic": {
    "account": "string",
    "service": "string",
    "event": "string",
    "project": "string",
    "factory": "string"
  },
  "params": {
    "addresses": [
      "string"
    ],
    "url": "string",
    "method": "GET",
    "retries": 0,
    "content_type": "application/json",
    "topic_arn": "string",
    "role_arn": "string",
    "topic_endpoint": "string",
    "access_key": "string",
    "project_id": "string",
    "topic_name": "string"
  }
}

400 Response

Responses

Status	Description	Schema
200	OK Subscription created	subscription
400	Bad Request Invalid input	string
401	Unauthorized Not authorized	string

delete subscription

Code samples

require 'rest-client'
require 'json'

headers = {
  'Accept' => '*/*',
  'X-Api-Key' => 'API_KEY'
}

result = RestClient.delete 'https://api.cloud.telestream.net/notifications/v2.0/subscriptions/{id}',
  params: {
  }, headers: headers

p JSON.parse(result)

import requests
headers = {
  'Accept': '*/*',
  'X-Api-Key': 'API_KEY'
}

r = requests.delete('https://api.cloud.telestream.net/notifications/v2.0/subscriptions/{id}', params={

}, headers = headers)

print r.json()

URL obj = new URL("https://api.cloud.telestream.net/notifications/v2.0/subscriptions/{id}");
HttpURLConnection con = (HttpURLConnection) obj.openConnection();
con.setRequestMethod("DELETE");
int responseCode = con.getResponseCode();
BufferedReader in = new BufferedReader(
    new InputStreamReader(con.getInputStream()));
String inputLine;
StringBuffer response = new StringBuffer();
while ((inputLine = in.readLine()) != null) {
    response.append(inputLine);
}
in.close();
System.out.println(response.toString());

package main

import (
       "bytes"
       "net/http"
)

func main() {

    headers := map[string][]string{
        "Accept": []string{"*/*"},
        "X-Api-Key": []string{"API_KEY"},

    }

    data := bytes.NewBuffer([]byte{jsonReq})
    req, err := http.NewRequest("DELETE", "https://api.cloud.telestream.net/notifications/v2.0/subscriptions/{id}", data)
    req.Header = headers

    client := &http.Client{}
    resp, err := client.Do(req)
    // ...
}

DELETE /subscriptions/{id}

Parameters


id string In path required none

Example responses

401 Response

Responses

Status	Description	Schema
200	OK Subscription deleted	None
401	Unauthorized Not authorized	string
404	Not Found Item not found	string

modify subscription

Code samples

require 'rest-client'
require 'json'

headers = {
  'Content-Type' => 'application/json',
  'Accept' => 'application/json',
  'X-Api-Key' => 'API_KEY'
}

result = RestClient.put 'https://api.cloud.telestream.net/notifications/v2.0/subscriptions/{id}',
  params: {
  }, headers: headers

p JSON.parse(result)

import requests
headers = {
  'Content-Type': 'application/json',
  'Accept': 'application/json',
  'X-Api-Key': 'API_KEY'
}

r = requests.put('https://api.cloud.telestream.net/notifications/v2.0/subscriptions/{id}', params={

}, headers = headers)

print r.json()

URL obj = new URL("https://api.cloud.telestream.net/notifications/v2.0/subscriptions/{id}");
HttpURLConnection con = (HttpURLConnection) obj.openConnection();
con.setRequestMethod("PUT");
int responseCode = con.getResponseCode();
BufferedReader in = new BufferedReader(
    new InputStreamReader(con.getInputStream()));
String inputLine;
StringBuffer response = new StringBuffer();
while ((inputLine = in.readLine()) != null) {
    response.append(inputLine);
}
in.close();
System.out.println(response.toString());

package main

import (
       "bytes"
       "net/http"
)

func main() {

    headers := map[string][]string{
        "Content-Type": []string{"application/json"},
        "Accept": []string{"application/json"},
        "X-Api-Key": []string{"API_KEY"},

    }

    data := bytes.NewBuffer([]byte{jsonReq})
    req, err := http.NewRequest("PUT", "https://api.cloud.telestream.net/notifications/v2.0/subscriptions/{id}", data)
    req.Header = headers

    client := &http.Client{}
    resp, err := client.Do(req)
    // ...
}

PUT /subscriptions/{id}

Modify subscription

Body parameter

{
  "topic": {
    "event": "string"
  },
  "params": {
    "addresses": [
      "string"
    ],
    "url": "string",
    "method": "GET",
    "retries": 0,
    "content_type": "application/json",
    "topic_arn": "string",
    "role_arn": "string",
    "topic_endpoint": "string",
    "access_key": "string",
    "project_id": "string",
    "topic_name": "string"
  }
}

Parameters


id string In path required none
body update_data In body optional none

Example responses

200 Response

{
  "id": "string",
  "type": "string",
  "topic": {
    "account": "string",
    "service": "string",
    "event": "string",
    "project": "string",
    "factory": "string"
  },
  "params": {
    "addresses": [
      "string"
    ],
    "url": "string",
    "method": "GET",
    "retries": 0,
    "content_type": "application/json",
    "topic_arn": "string",
    "role_arn": "string",
    "topic_endpoint": "string",
    "access_key": "string",
    "project_id": "string",
    "topic_name": "string"
  }
}

401 Response

Responses

Status	Description	Schema
200	OK Subscription updated	subscription
401	Unauthorized Not authorized	string
404	Not Found Item not found	string

get subscription

Code samples

require 'rest-client'
require 'json'

headers = {
  'Accept' => 'application/json',
  'X-Api-Key' => 'API_KEY'
}

result = RestClient.get 'https://api.cloud.telestream.net/notifications/v2.0/subscriptions/{id}',
  params: {
  }, headers: headers

p JSON.parse(result)

import requests
headers = {
  'Accept': 'application/json',
  'X-Api-Key': 'API_KEY'
}

r = requests.get('https://api.cloud.telestream.net/notifications/v2.0/subscriptions/{id}', params={

}, headers = headers)

print r.json()

URL obj = new URL("https://api.cloud.telestream.net/notifications/v2.0/subscriptions/{id}");
HttpURLConnection con = (HttpURLConnection) obj.openConnection();
con.setRequestMethod("GET");
int responseCode = con.getResponseCode();
BufferedReader in = new BufferedReader(
    new InputStreamReader(con.getInputStream()));
String inputLine;
StringBuffer response = new StringBuffer();
while ((inputLine = in.readLine()) != null) {
    response.append(inputLine);
}
in.close();
System.out.println(response.toString());

package main

import (
       "bytes"
       "net/http"
)

func main() {

    headers := map[string][]string{
        "Accept": []string{"application/json"},
        "X-Api-Key": []string{"API_KEY"},

    }

    data := bytes.NewBuffer([]byte{jsonReq})
    req, err := http.NewRequest("GET", "https://api.cloud.telestream.net/notifications/v2.0/subscriptions/{id}", data)
    req.Header = headers

    client := &http.Client{}
    resp, err := client.Do(req)
    // ...
}

GET /subscriptions/{id}

Parameters


id string In path required none

Example responses

200 Response

{
  "id": "string",
  "type": "string",
  "topic": {
    "account": "string",
    "service": "string",
    "event": "string",
    "project": "string",
    "factory": "string"
  },
  "params": {
    "addresses": [
      "string"
    ],
    "url": "string",
    "method": "GET",
    "retries": 0,
    "content_type": "application/json",
    "topic_arn": "string",
    "role_arn": "string",
    "topic_endpoint": "string",
    "access_key": "string",
    "project_id": "string",
    "topic_name": "string"
  }
}

401 Response

Responses

Status	Description	Schema
200	OK OK	subscription
401	Unauthorized Not authorized	string
404	Not Found Item not found	string

Schemas

subscription

{
  "id": "string",
  "type": "string",
  "topic": {
    "account": "string",
    "service": "string",
    "event": "string",
    "project": "string",
    "factory": "string"
  },
  "params": {
    "addresses": [
      "string"
    ],
    "url": "string",
    "method": "GET",
    "retries": 0,
    "content_type": "application/json",
    "topic_arn": "string",
    "role_arn": "string",
    "topic_endpoint": "string",
    "access_key": "string",
    "project_id": "string",
    "topic_name": "string"
  }
}

Properties


id string optional [read-only] Subscription identifier read-only
type string required Type of subscription (email, webhook, sns, aeg, pubsub)
topic topic required none
params params required none

params

{
  "addresses": [
    "string"
  ],
  "url": "string",
  "method": "GET",
  "retries": 0,
  "content_type": "application/json",
  "topic_arn": "string",
  "role_arn": "string",
  "topic_endpoint": "string",
  "access_key": "string",
  "project_id": "string",
  "topic_name": "string"
}

Properties


addresses [string] optional (for email subscription type); E-mail addresses
url string optional (for webhook subscription type); Webhook URL
method string optional (for webhook subscription type); HTTP method; default: POST (GET, POST)
retries integer optional (for webhook subscription type); Number of retries before forgetting the notification; default: 0
content_type string optional (for webhook subscription type); default: application/json (application/json, application/x-www-form-urlencoded)
topic_arn string optional (for sns subscription type) identifier of an AWS SNS Topic that events will be posted to.
role_arn string optional (for sns subscription type) identifier of an AWS IAM Role that will be used for authorization.
topic_endpoint string optional (for aeg subscription type) address of an Azure Event Grid Topic that events will be posted to.
access_key string optional (for aeg subscription type) secret access key that authorizes Telestream Cloud to write to an Azure Event Grid Topic.
project_id string optional (for pubsub subscription type) id of a Google Cloud project that hosts the topic.
topic_name string optional (for pubsub subscription type) name of a Google Cloud Pub/Sub topic to which notifications will be published.

Enumerated Values


method GET
method POST
content_type application/json
content_type application/x-www-form-urlencoded

topic

{
  "account": "string",
  "service": "string",
  "event": "string",
  "project": "string",
  "factory": "string"
}

Properties


account string optional [read-only] Account identifier connected to subscription notification read-only
service string required Name of service (qc, flip, tts)
event string required Name of the event; Quality Control (media-passed, media-error, media-warning, media-rejected, media-canceled, job-created, job-progress), Flip (video-created, video-encoded, encoding-complete, encoding-progress), Transcription (job-created, job-completed, job-error, job-progress)
project string optional (for tts, qc service); Project ID
factory string optional (for flip service); Factory ID

update_data

{
  "topic": {
    "event": "string"
  },
  "params": {
    "addresses": [
      "string"
    ],
    "url": "string",
    "method": "GET",
    "retries": 0,
    "content_type": "application/json",
    "topic_arn": "string",
    "role_arn": "string",
    "topic_endpoint": "string",
    "access_key": "string",
    "project_id": "string",
    "topic_name": "string"
  }
}

Properties


topic update_topic optional none
params params optional none

update_topic

{
  "event": "string"
}

Properties


event string optional Name of the event; Quality Control (media-passed, media-error, media-warning, media-rejected, media-canceled, job-created, job-progress), Flip (video-created, video-encoded, encoding-complete, encoding-progress), Transcription (job-created, job-completed, job-error, job-progress)