When you use Intelligent Media Services (IMS) for media asset uploads, media processing, and online editing, you can configure callback events to receive timely updates on task progress and status, allowing you to coordinate subsequent business operations.
Callback methods
Introduction
IMS supports two callback methods for receiving event notifications: HTTP requests and MNS queues.
-
HTTP request: IMS sends event notifications to your service. You deploy an HTTP service to receive callback messages and configure a callback URL in the console or by calling an API operation. When an event occurs, the IMS server sends an HTTP POST request to the callback URL with the message content in the HTTP body.
-
MNS queue: IMS writes event notifications to a message queue. You authorize IMS to access Simple Message Queue (formerly MNS), create or select an existing queue, and configure the queue name in the console or by calling an API operation. When an event occurs, IMS writes the callback content to the queue. You can then read the queue to retrieve the messages.
Pros and cons
|
Comparison |
HTTP request |
MNS queue |
|
Reliability |
Messages may be lost if the receiving HTTP service experiences issues, such as a crash or restart. |
If the configuration is correct, message callbacks are almost always successful. This method offers higher reliability. |
|
Security |
Any HTTP client can send a request to the callback URL. You can use callback authentication to filter unauthorized requests. For more information, see Callback authentication. |
Only authorized parties can read from and write to the message queue. This method offers higher security. |
|
Convenience |
Easier to set up. Simply deploy a service to receive messages. |
Requires enabling and configuring MNS. You must also develop and deploy a program to consume the messages. |
Callback protocols
|
Callback method |
Description |
|
HTTP request |
|
|
MNS queue |
The messages received from the queue are JSON strings. For examples of the message body and parameter descriptions, see Event list. |
Callback validation and retries
|
Callback method |
Was the callback successful? |
Callback Retries |
|
HTTP request |
A callback is successful if the receiving service responds with HTTP status code 200. A callback fails if the status code is not 200 or the response time exceeds 3 seconds. IMS determines success based only on the HTTP status code and ignores the response body. |
If a callback fails due to a configuration issue such as an incorrect callback URL or an unavailable receiving service, IMS retries two more times at 1-second intervals. If all three attempts fail, the message is discarded. |
|
MNS queue |
A callback is considered successful if the message is written to the MNS queue successfully. Otherwise, the callback is considered failed. |
If writing the message to the MNS queue fails due to a configuration issue, IMS retries two more times at 1-second intervals. Examples of configuration issues include not granting IMS access to Simple Message Queue (formerly MNS), using a non-public-network queue address, or specifying an incorrect queue name. If all three attempts fail, the message is discarded. |
MNS queue callbacks provide higher reliability. If the configuration is correct, message callbacks are almost always successful.
Callback event types
IMS provides callback events for media asset uploads, media processing, online editing, and other operations. You can configure specific callback events to receive timely updates on task progress and status. For more information, see Event list.