Notification API

The PCast™ streaming platform can notify your backend via web hook on certain stream events.

• Stream publishing starts
• Stream publishing stops
• Live HLS and DASH streams available
• Video on demand asset available

You can set the callback endpoint for your application using a PUT request.

PUT /pcast/application/<applicationId>/callback HTTP/1.1
Host: pcast.phenixrts.com
Accept: application/json
Content-Type: application/json
Content-Length: 194
Authorization: Basic YXBwbGljYXRpb25JZDpzZWNyZXQ=
 
{
    "callback": {
        "protocol": "<protocol>",
        "host": "<host>",
        "port": <port>,
        "method": "<method>",
        "path": "<path>",
        "query": "<query>"
    }
}

The platform will return a successful response that contains a "status" field. The HTTP status code is set according to the status field.

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
Content-Length: 107
 
{"status":"ok","endpoint":"POST https://webhook.site:443/1234abcd-1234-6789-0123-abcdef123456?param1=true"}

The streaming platform notifies the callback endpoint when certain platform events occur.

We will be using the callback.method of POST in the examples for each notification type below. However "GET", "POST" or "PUT" are fully supported.

To debug notifications, consider the webhook.site online tool.

Details about the event, such as channelId and sessionId, will be in tags in the content of the notification.

POST <callback.path> HTTP/1.1
Host: <callback.host>:<callback.port>
Content-Type: application/json
Content-Length: 250
 
{
    "apiVersion": 0,
    "entity", "stream",
    "what", "started",
    "data": {
        "streamId": "<streamId>",
        "tags": [
            "<tag>"
        ]
    },
    "sessionId": "<sessionId>",
    "timestamp": "2019-01-23T21:12:55.384Z"
}

POST <callback.path> HTTP/1.1
Host: <callback.host>:<callback.port>
Content-Type: application/json
Content-Length: 304
 
{
    "apiVersion": 0,
    "entity", "stream",
    "what", "ended",
    "data": {
        "streamId": "<streamId>",
        "tags": [
            "<tag>"
        ]
        "duration": 11457,
        "reason": "<reason>"
    },
    "sessionId": "<sessionId>",
    "timestamp": "2019-01-23T21:12:55.384Z"
}

Reach devices with adaptive multi-bitrate live streaming capabilities. Currently HLS and MPEG-DASH playlists in adaptive multi-bitrate and various quality levels are supported.

This also makes the stream available inside all our SDKs using the streaming capability when subscribing.

POST <callback.path> HTTP/1.1
Host: <callback.host>:<callback.port>
Content-Type: application/json
Content-Length: 222
 
{
    "apiVersion": 0,
    "entity", "stream",
    "what", "live",
    "data": {
        "streamId": "<streamId>",
        "uri": "<uri>"
    },
    "sessionId": "<sessionId>",
    "timestamp": "2019-01-23T21:12:55.384Z"
}

Provide adaptive multi-bitrate on-demand streaming capabilities. Currently HLS and MPEG-DASH playlists as adaptive multi-bitrate and specific quality levels are supported.

This also makes the stream available inside all our SDKs using the "on-demand" capability when subscribing.

POST <callback.path> HTTP/1.1
Host: <callback.host>:<callback.port>
Content-Type: application/json
Content-Length: 227
 
{
    "apiVersion": 0,
    "entity", "stream",
    "what", "on-demand",
    "data": {
        "streamId": "<streamId>",
        "uri": "<uri>",
        "isPrimary": true,
        "isVariant": false
    },
    "sessionId": "<sessionId>",
    "timestamp": "2019-01-23T21:12:55.384Z"
}

You can authenticate notifications by using the HMAC-SHA256 authentication scheme. HMAC refers to hash-based message authentication code.

To authenticate a notification, you must assert that it contains valid X-PCast-Content-Sha256 and Authorization headers.

To validate X-PCast-Content-Sha256 header you need to stringify the request body, and generate a SHA-256 hash from it. Then you need to compare generated hash with the hash in X-PCast-Content-Sha256.

//Validate X-PCast-Content-Sha256
function isContentSha256Valid(requestStringBody, contentSha256Header) {
  var generatedContentHash = crypto
    .createHash('sha256')
    .update(requestStringBody)
    .digest('base64');
 
  return contentSha256Header === generatedContentHash;
}

The Authorization header consists of the HMAC hash of the request prefixed with HMAC-SHA256.

Authorization = 'HMAC-SHA256 ' + hash (HMAC created using the SHA-256 hash algorithm with the application secret as key).

To validate the HMAC hash of the Authorization header you must compare it with the one regenerated from the canonical representation of the request using your application secret as a key.

String-To-Sign = HTTP_METHOD + path_and_query + content_sha256_header + content_type_header + pcast_timestamp_header

// Generate string to sign
function getStringToSign(
  method,
  path,
  contentSha256,
  contentType,
  unixTimestamp
) {
  return method + path + contentSha256 + contentType + unixTimestamp;
}

// Validate Authorization header
function isAuthorizationHeaderValid(secret, stringToSign, authorizationHeader) {
  var generatedHmacSha256Hash =
    'HMAC-SHA256 ' +
    crypto.createHmac('sha256', secret).update(stringToSign).digest('base64');
 
  return generatedHmacSha256Hash === authorizationHeader;
}