Overview
BlendVision Encoder supports Event Webhook to send callbacks when the status of the encoding process gets updated. An HTTP request with JSON format content will be sent to the integrated server.
How to setup Event Webhook
You can set up Webhooks on the Notification session when Creating a new Project on console.
- Notification type
- Encoding starts/ends: To receive updates only the encoding job starts and ends (Default setting)
- All events: To provide detailed status updates for each encoding job stage
- Auth header name & Auth header value
To ensure the authentication is implemented on the callback server in order to block from malicious attacks, you can fill the API Key in the header settings, so that your callback server can block unknown connections without valid authentication.
- Webhook URL
Fill in the server URL that you intend to integrate with BlendVision Encoder event callback .
- Test the Webhook
You can verify the connection before running a real encoding Job. Press“Test webhook URL” button to fire a sample webhook event to the callback server. The server sample response will be displayed on “Console message” field if the network connection is available.
Encoding Stages
An encoding Job will go through the following stages: Ingest, Queue, Encode, Output, CDN. For a detailed definition of each stage, please refer to the Job Stages.
REST API
The callback request contains HTTP header and JSON body.
Header
If you set fields in the auth header, the customized headers are included in the request.
Body
The JSON body can be separated into two types of events, (1) the stage-change event and (2) the summary event. Stage-change events will be sent out whenever the encoding job changes the stage. If you select to receive only starts/ends events, you will only receive stage-change event with the job stage = ingest. The summary event will be sent out when the encoding job is finished. Depending on the project type you choose (either encoding of streaming), the definition of “Job Ends” will be different.
(1) The Stage-change Event
During the Job processing runtime, stage-change events will be sent out to notify you for every stage change. Details of the event and some examples are provided below.
|
Field |
Datatype |
Description |
|
job_id |
UUID |
The Job ID |
|
project_id |
UUID |
The Project ID |
|
project_name |
string |
Name of the Project |
|
stage |
string |
Stage describes the certain phase of an encoding Job. Job stages are separated into [ingest, queue, encode, output, cdn] |
|
status |
string |
To indicate the status of a specific stage. Status includes [processing, canceled, failed] e.g. If the stage is ingest and the status is canceled. It means the Job is canceled at the ingesting stage. |
|
src_filename |
string |
The source video file name |
|
message |
string (optional) |
Detailed message when the Job is failed |
Example: failed in ingest stage
{
"job_id": "71f5aae9-7cd5-4010-8dbc-8d420b15e2f2",
"project_id": "4d30fe31-107f-4ee7-9d96-941a91c892a0",
"project_name": "custome_xxx",
"src_filename": "Sample Videos Dummy Videos For Demo Use.mp4",
"stage": "ingest",
"status": "failed",
"message": "ingest fails. file format is not supported."
}
Example: processing in ingest stage
{
"job_id": "71f5aae9-7cd5-4010-8dbc-8d420b15e2f2",
"project_id": "4d30fe31-107f-4ee7-9d96-941a91c892a0",
"project_name": "custome_xxx",
"src_filename": "Sample Videos Dummy Videos For Demo Use.mp4",
"stage": "ingest",
"status": "processing"
}
(2) The Summary Event
Once the job finishes, no matter it is completed or failed, a final summary event will be sent to the webhook subscriptions. This summary event has detailed information about the final encoding production.
|
Field |
Datatype |
Description |
|
job_id |
UUID |
The Job ID |
|
project_id |
UUID |
The Project ID |
|
project_name |
string |
Name of the Project |
|
src_filename |
string |
The source video file name |
|
message |
string(optional) |
Detailed message when the Job is failed |
|
encoding_result |
EncodingResult object |
Describe the output destination and file path of the encoding production |
|
stage_summary |
StageSummary object |
A summary to indicates each stages’ status of the encoding job |
[Object] EncodingResult
|
Field |
Datatype |
Description |
|
video_duration |
number |
The encoded content duration in seconds |
|
output_endpoints |
array of Output object |
・Final encoding production that deployed to customer’s output destination ・Will be available when the project type = encoding |
|
cdn_endpoints |
array of Output object |
・Final encoding production that deployed to the CDN endpoint ・Will be available when the project type = streaming |
[Object] Output
|
field |
datatype |
description |
||||||
|
profile_name |
string (optional) |
Only available when the type=video and when SmartABR feature is enabled. When SmartABR is enabled, there will be multiple output endpoints which will include different profile combinations. This field will indicate which profiles are included in each endpoint by listing out profile names respectively. |
||||||
|
type |
string |
The content type, such as video, thumbnail |
||||||
|
protocol |
string |
The general type of such content. The value is related to the type:
|
||||||
|
url |
string |
The final output URL endpoint |
[Object] StageSummary
|
Field |
Datatype |
Description |
|
ingest |
string |
Status of the ingest stage. To indicate the status of a specific stage. Status includes [processing, canceled, failed] |
|
queue |
string |
Status of the queue stage. To indicate the status of a specific stage. Status includes [processing, canceled, failed] |
|
encode |
string |
Status of the encode stage. To indicate the status of a specific stage. Status includes [processing, failed] |
|
output |
string |
Status of the output stage. To indicate the status of a specific stage. Status includes [processing, failed] |
|
cdn |
string (optional) |
Status of the cdn stage. To indicate the status of a specific stage. Status includes [processing, failed] |
Example: SmartABR is disabled
{
"encoding_result":{
"video_duration" : 30.01,
"output_endpoints": [
{
"protocol": "vtt",
"type": "thumbnail",
"url": "https://fakeaccount.blob.core.windows.net/ca3912c4-24dc-4c85-a0cf-1f41594c38b8/4269de02-1519-4180-a426-c91867bdf33a/thumbnail/thumbnails.vtt"
},
{
"protocol": "dash",
"type": "video",
"url": "https://fakeaccount.blob.core.windows.net/62c019f4-6414-402c-a549-f9d9443bf363/4269de02-1519-4180-a426-c91867bdf33a/dash.mpd"
},
{
"protocol": "hls",
"type": "video",
"url": "https://fakeaccount.blob.core.windows.net/62c019f4-6414-402c-a549-f9d9443bf363/4269de02-1519-4180-a426-c91867bdf33a/hls.m3u8"
}
],
"cdn_endpoints": [
{
"protocol": "vtt",
"type": "thumbnail",
"url": "https://fakecdn.azureedge.net/ca3912c4-24dc-4c85-a0cf-1f41594c38b8/4269de02-1519-4180-a426-c91867bdf33a/thumbnail/thumbnails.vtt"
},
{
"protocol": "dash",
"type": "video",
"url": "https://fakecdn.azureedge.net/62c019f4-6414-402c-a549-f9d9443bf363/5d3288a1-ee4a-4b73-9bab-aff7bb3a080b/dash.mpd"
},
{
"protocol": "hls",
"type": "video",
"url": "https://fakecdn.azureedge.net/62c019f4-6414-402c-a549-f9d9443bf363/5d3288a1-ee4a-4b73-9bab-aff7bb3a080b/hls.m3u8"
}
]
},
"job_id": "71f5aae9-7cd5-4010-8dbc-8d420b15e2f2",
"project_id": "4d30fe31-107f-4ee7-9d96-941a91c892a0",
"project_name": "custome_xxx",
"stage_summary": {
"ingest": "completed",
"queue": "completed",
"encode": "completed",
"output": "completed",
"cdn": "completed"
},
"src_filename": "Sample Videos Dummy Videos For Demo Use.mp4"
}
Example: SmartABR is enabled
{
"encoding_result":{
"video_duration" : 140000.01,
"output_endpoints": [
{
"protocol": "vtt",
"type": "thumbnail",
"url": "https://fakeaccount.blob.core.windows.net/ca3912c4-24dc-4c85-a0cf-1f41594c38b8/4269de02-1519-4180-a426-c91867bdf33a/thumbnail/thumbnails.vtt"
},
{
"profile_name": "480p-3Mbps, 360p-1.4Mbps, 240p-800kbps",
"protocol": "dash",
"type": "video",
"url": "https://fakeaccount.blob.core.windows.net/62c019f4-6414-402c-a549-f9d9443bf363/f3f43f20-b870-4a64-966e-efc4746400d6/dash_57d453d5-e8a2-42b3-a73b-82cddac411c9.mpd"
},
{
"profile_name": "360p-1.4Mbps, 240p-800kbps",
"protocol": "dash",
"type": "video",
"url": "https://fakeaccount.blob.core.windows.net/62c019f4-6414-402c-a549-f9d9443bf363/f3f43f20-b870-4a64-966e-efc4746400d6/dash_9012bdee-a676-4453-8c5d-a511db484abf.mpd"
},
{
"profile_name": "240p-800kbps",
"protocol": "dash",
"type": "video",
"url": "https://fakeaccount.blob.core.windows.net/62c019f4-6414-402c-a549-f9d9443bf363/f3f43f20-b870-4a64-966e-efc4746400d6/dash_a6b2efaf-3dd9-4ff8-b85b-44661da6ecae.mpd"
},
{
"profile_name": "480p-3Mbps, 360p-1.4Mbps, 240p-800kbps",
"protocol": "hls",
"type": "video",
"url": "https://fakeaccount.blob.core.windows.net/62c019f4-6414-402c-a549-f9d9443bf363/f3f43f20-b870-4a64-966e-efc4746400d6/hls_57d453d5-e8a2-42b3-a73b-82cddac411c9.m3u8"
},
{
"profile_name": "360p-1.4Mbps, 240p-800kbps",
"protocol": "hls",
"type": "video",
"url": "https://fakeaccount.blob.core.windows.net/62c019f4-6414-402c-a549-f9d9443bf363/f3f43f20-b870-4a64-966e-efc4746400d6/hls_9012bdee-a676-4453-8c5d-a511db484abf.m3u8"
},
{
"profile_name": "240p-800kbps",
"protocol": "hls",
"type": "video",
"url": "https://fakeaccount.blob.core.windows.net/62c019f4-6414-402c-a549-f9d9443bf363/f3f43f20-b870-4a64-966e-efc4746400d6/hls_a6b2efaf-3dd9-4ff8-b85b-44661da6ecae.m3u8"
}
],
"cdn_endpoints": [
{
"protocol": "vtt",
"type": "thumbnail",
"url": "https://fakecdnaccount.azureedge.net/ca3912c4-24dc-4c85-a0cf-1f41594c38b8/4269de02-1519-4180-a426-c91867bdf33a/thumbnail/thumbnails.vtt"
},
{
"profile_name": "480p-3Mbps, 360p-1.4Mbps, 240p-800kbps",
"protocol": "dash",
"type": "video",
"url": "https://fakecdnaccount.azureedge.net/62c019f4-6414-402c-a549-f9d9443bf363/f3f43f20-b870-4a64-966e-efc4746400d6/dash_57d453d5-e8a2-42b3-a73b-82cddac411c9.mpd"
},
{
"profile_name": "360p-1.4Mbps, 240p-800kbps",
"protocol": "dash",
"type": "video",
"url": "https://fakecdnaccount.azureedge.net/62c019f4-6414-402c-a549-f9d9443bf363/f3f43f20-b870-4a64-966e-efc4746400d6/dash_9012bdee-a676-4453-8c5d-a511db484abf.mpd"
},
{
"profile_name": "240p-800kbps",
"protocol": "dash",
"type": "video",
"url": "https://fakecdnaccount.azureedge.net/62c019f4-6414-402c-a549-f9d9443bf363/f3f43f20-b870-4a64-966e-efc4746400d6/dash_a6b2efaf-3dd9-4ff8-b85b-44661da6ecae.mpd"
},
{
"profile_name": "480p-3Mbps, 360p-1.4Mbps, 240p-800kbps",
"protocol": "hls",
"type": "video",
"url": "https://fakecdnaccount.azureedge.net/62c019f4-6414-402c-a549-f9d9443bf363/f3f43f20-b870-4a64-966e-efc4746400d6/hls_57d453d5-e8a2-42b3-a73b-82cddac411c9.m3u8"
},
{
"profile_name": "360p-1.4Mbps, 240p-800kbps",
"protocol": "hls",
"type": "video",
"url": "https://fakecdnaccount.azureedge.net/62c019f4-6414-402c-a549-f9d9443bf363/f3f43f20-b870-4a64-966e-efc4746400d6/hls_9012bdee-a676-4453-8c5d-a511db484abf.m3u8"
},
{
"profile_name": "240p-800kbps",
"protocol": "hls",
"type": "video",
"url": "https://fakecdnaccount.azureedge.net/62c019f4-6414-402c-a549-f9d9443bf363/f3f43f20-b870-4a64-966e-efc4746400d6/hls_a6b2efaf-3dd9-4ff8-b85b-44661da6ecae.m3u8"
}
]
},
"job_id": "71f5aae9-7cd5-4010-8dbc-8d420b15e2f2",
"project_id": "4d30fe31-107f-4ee7-9d96-941a91c892a0",
"project_name": "custome_xxx",
"stage_summary": {
"ingest": "completed",
"queue": "completed",
"encode": "completed",
"output": "completed",
"cdn": "completed"
},
"src_filename": "Sample Videos Dummy Videos For Demo Use.mp4"
}