Set up Webhooks & Notifications

AuroraCloud Supports Webhooks!

AuroraCloud uses webhooks to automatically notify your system when transcoding tasks complete.

What Are Webhooks?

Webhooks are HTTP callbacks that deliver real-time notifications to your system when events occur. In this case, AuroraCloud sends an HTTP POST request to your specified URL when a transcoding task finishes.

How to Configure Your Webhook

Step 1: Set Up Your Webhook Endpoint

Create an HTTP endpoint on your server that can:

Accept POST requests
Process JSON data
Return a 200 OK response

Step 2: Register Your Webhook URL 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",
  "storage_sk": "xqTJfWzDA******DFm9WOsBChCRF",
  "notify": "https://your-endpoint.com/transcode-callback"
}

Key Parameter:

notify: Your publicly accessible HTTPS endpoint that will receive webhook notifications

Webhook Notification Format

Request Details

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

Example Webhook Payload

{  
  "code": 0,
  "msg": "succeeded",
  "callback_url": "http://xxx.com/notify",
  "data": [
    {
      "task_id": "20220420111542664667cccc3d179880",
      "input": "https://input-source.com/test.mp4",
      "output": "oss://output-bucket/path/test.mp4",
      "format": "mp4",
      "status": "succeeded",
      "duration": 30.0,
      "spend_time": 2.0
    },
    {
      "task_id": "20220420111542664667cccc3d179780",
      "status": "failed",
      "error_code": 1003,
      "error_msg": "Invalid input file"
    }
  ]
}

Webhook Payload Parameters

Parameter	Type	Required	Description
`code`	int	Yes	Global status code (fixed to `0`)
`msg`	string	Yes	Aggregated status: `succeeded` (all tasks succeeded) or `failed` (at least one task failed)
`callback_url`	string	Yes	Redundant field that matches your configured `notify_url`
`data`	JSON Array	Yes	Array of task results (supports batch processing)

Task Result Parameters

Parameter	Type	Required	Description
`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

How to Respond to Webhooks

HTTP Status Code:
- Your server must return 200 OK
- If AuroraCloud doesn't receive a 200 OK, it will retry delivery up to 3 times with 5-second intervals
Response Body:
- AuroraCloud ignores the body content
- You can return an empty body or simple acknowledgment (e.g., {"ack": true})

Best Practices & Security Recommendations

Idempotency: Use task_id to deduplicate potential retries to avoid processing the same notification multiple times
Validation: Verify the source of webhook requests by:
- Checking request source IPs
- Enabling signature headers (contact AuroraCloud support for setup)
Error Handling:
- Set up alerts or remediation workflows for status=failed tasks
- Use error_code and error_msg for debugging and monitoring
Reliability:
- Ensure your webhook endpoint is highly available
- Implement logging to track webhook deliveries and responses

Need Help?

Contact AuroraCloud support for additional assistance with webhook setup and configuration.

Visionular