How to Configure Transcoding Task Callbacks?

Overview

Upon completion of a transcoding task, AuroraCloud asynchronously sends task status and metadata to your designated endpoint via an HTTP POST request to the configured notify_url.

This guide details callback configuration, data protocol specifications, and parameter semantics.

Configuring the Callback Endpoint (Notify URL)

In the design of AuroraCloud, the callback address (notify_url) and the storage target (such as a S3 Bucket) are positioned at the same configuration level to fully accommodate the diverse business scenario needs of customers:

Binding a Callback During Storage Configuration

API Endpoint:

POST https://api.visionular.com/vodencoding/v1/add_storage

Request Body Example:

{  
  "region": "cn-zhangjiakou",  
  "type": "oss",  
  "bucket": "your-bucket-name",  
  "prefix": "custom/output/path",  
  "storage_ak": "LTAI5t5******EWduEV3Pja",  // Replace with your Access Key  
  "storage_sk": "xqTJfWzDA******DFm9WOsBChCRF",  // Replace with your Secret Key  
  "notify": "https://your-endpoint.com/transcode-callback"  // Callback URL  
}

Key Parameters:

notify: A publicly accessible HTTPS endpoint.

Callback Protocol Specifications

Request Method and Data Format

Method: POST
Content-Type: application/json
Body: JSON payload containing task status and metadata.

Callback Payload Example

{  
    "code": 0,                                // Global status code  
    "msg": "succeeded",                       // Aggregated status  
    "callback_url": "http://xxx.com/notify",  // Redundant field (matches notify_url)  
    "data": [                                 // Task result array  
        {  
            "task_id": "20220420111542664667cccc3d179880",  
            "input": "https://input-source.com/test.mp4",  
            "output": "oss://output-bucket/path/test.mp4",  
            "format": "mp4",                  // Output format (mp4/hls/dash/flv)  
            "status": "succeeded",            // Task status  
            "duration": 30.0,                 // Media duration (seconds)  
            "spend_time": 2.0                 // Processing time (seconds)  
        },  
        {  
            "task_id": "20220420111542664667cccc3d179780",  
            "status": "failed",               // Failed task example  
            "error_code": 1003,               // Error code (if available)  
            "error_msg": "Invalid input file" // Error description (if available)  
        }  
    ]  
}

Parameter Semantics

Parameter	Type	Required	Description
`code`	int	Yes	Global status code (fixed to `0`).
`msg`	string	Yes	Aggregated status: `succeeded`– All tasks succeeded
`failed` – At least one task failed.`data`	JSON Array	Yes	Array of task results (supports batch processing).
`task_id`	string	Yes	Unique task identifier for logging and troubleshooting.
`input`	string	Conditional	Input media URI (returned for successful tasks).
`output`	string	Conditional	Output file path (returned for successful tasks).
`format`	string	Conditional	Output format: `mp4`/`hls`/`dash`/`flv` (returned for successful tasks).
`status`	string	Yes	Task status: `succeeded` or `failed`.
`duration`	float	Optional	Media duration in seconds (may be omitted for failed tasks).
`spend_time`	float	Optional	Processing time in seconds.
`error_code`	int	Optional	Error code for failed tasks (e.g., `1003`).
`error_msg`	string	Optional	Error description for failed tasks.

Server Response Requirements

HTTP Status Code:
- Return 200 OK; otherwise, AuroraCloud retries delivery (max 3 attempts, 5-second intervals).
Response Body:
- AuroraCloud ignores the body content. Return an empty body or simple acknowledgment (e.g., {"ack": true}).

Best Practices & Security Recommendations

Idempotency: Use task_id to deduplicate potential retries.
Validation: Verify request source IPs or enable signature headers (contact support for setup).
Error Handling: Trigger alerts or remediation workflows for status=failed tasks using error_code.

Visionular