Callbacks

You can use LightFlow callbacks to let your application track the status of assets asynchronously. When a new media asset is published, LightFlow will make a request to the callback URL reporting whether the process was successful or if there was any error. Callbacks are defined in the endpoint responsible for publishing new assets.

BASH

curl -XPOST 'https://api.lightflow.media/assets' \
  -H 'authorization: Bearer API_TOKEN' \
  -H 'content-type: application/json' \
  -d '{ \
      "parameters": { \
          "input": { \
              "urlPath": "http://someserver.com/VideoSample.mp4" \
          }, \
          "perceptual-quality": { \
              "h264": { \
                  "maxBitrate": 8000, \
                  "minBitrate": 250, \
                  "maxResolution": 1080, \
                  "targetQuality": 100 \
              } \
          }, \
          "callbacks": [ \
              { \
                  "url":"https://callback.epiclabs/ingest", \
                  "headers":[ \
                    { \
                      "name": "Authorization", \
                      "value" : "Bearer <JWT TOKEN>" \
                    }, \
                    { \
                        "name": "X-Custom-Header", \
                        "value" : "X-Custom-Header-Value"
                    } \
                  ], \
                  "method":"POST", \
              } \
          ] \'
      } \
    }'

Arguments

url: Defines the publicly accessible endpoint exposed by you and that will be called by LightFlow when the callback mechanism is triggered. Mail addresses are also supported following the format "mailto:johndoe@epiclabs.io". An email will be delivered to the specified address.
headers: List of HTTP headers that will be sent by LightFlow when doing a request to your endpoint. This is an optional field. Its default value is empty. Accepts an array of objects with the keys 'name' and 'value'.
method: HTTP request methods. This is an optional field. Its default value is 'POST'. Possible values:
- GET: As it is a GET request, request body will be empty. Parameters 'status' and 'endDate' are variables provided by LightFlow to your endpoint as query parameters.
- POST: This is the default method. Request body format:

BASH

{
    "uuid": "6b48fbce-cd10-459c-b397-5673e4bbafaf",
    "assetName": "T1S03",
    "inputUrl": "https://storage.googleapis.com/T1S03.mp4"
    "username": "jonhdoe@epiclabs.io",
    "startDate": "2019-02-14T20:32:48.898Z",
    "endDate": "2019-02-14T20:43:11.825Z",
    "status": "finished",
    "metadata": {},
    "duration": 120,
    "assetUrl": "https://dashboard.lightflow.media/perceptual-quality/6b48fbce-cd10-459c-b397-5673e4bbafaf",
    "thumbnail": "http://video.lightflow.media/thumb/6b48fbce-cd10-459c-b397-5673e4bbafaf?time=50&width=320"
  }

Description of callback properties:

uuid: uuid of the published asset.
assetName: Name of the asset as it was set during its creation.
inputUrl: URL or path from which the asset video source was retrieved.
username: User who published the asset.
startDate: When the asset processing started.
endDate: When the asset processing ended.
status: Asset status
metadata: Metadata associated with the asset as it was set during its creation.
duration: Duration of the asset, in seconds.
assetUrl: Link in LightFlow dashboard that shows information about the published asset.
thumbnail: Link to a thumbnail extracted from the asset.

- PUT: Request body:

BASH

{
    "uuid": "6b48fbce-cd10-459c-b397-5673e4bbafaf",
    "assetName": "T1S03",
    "inputUrl": "https://storage.googleapis.com/T1S03.mp4"
    "username": "jonhdoe@epiclabs.io",
    "startDate": "2019-02-14T20:32:48.898Z",
    "endDate": "2019-02-14T20:43:11.825Z",
    "status": "finished",
    "metadata": {},
    "duration": 120,
    "assetUrl": "https://dashboard.lightflow.media/perceptual-quality/6b48fbce-cd10-459c-b397-5673e4bbafaf",
    "thumbnail": "http://video.lightflow.media/thumb/6b48fbce-cd10-459c-b397-5673e4bbafaf?time=50&width=320"
  }

source: With this field you can define which callbacks you would like to use. When you are publishing an asset in LightFlow you can define which type of encoder you would like to use: the LightFlow encoder (the preferred method) or any encoder resource that you already have (ex: Brightcove Zencoder). Third party encoders typically have their own callback mechanisms. This is an optional field. Its default value is 'lightflow'. Possible values:
- lightflow: default option. LightFlow is responsible for callbacks.
- encoder: only applicable if client is using a third party encoder. LightFlow will pass callback information to the specified encoder, so the encoder will be the one triggering the callback when encoding is done.
onSuccess: Optional field, its default value is 'true'. Defines in which cases the callback should be executed. Possible values:
- true: callback is executed when the asset is published successfully.
- false: callback won't be executed when the asset is published successfully.
on Failure: Optional field, its default value is 'true'. Defines in which cases the callback should be executed. Possible values:
- true: callback is executed when there was an error while publishing the asset.
- false: callback won't be executed when the asset could not be published due to any error.
onProgressEncoding: Optional field, its default value is 'false'. Defines if callback should be executed to send messages about encoding progress. Possible values:
- true: callback is executed when an encoding task is completed.
- false: callback won't be executed when an encoding task is completed