When you use features of Intelligent Media Services (IMS) such as media asset upload, media processing, and online editing, you can configure callback events to obtain the task progress and status at the earliest opportunity. This way, you can perform other business operations based on the events. This topic describes the basic information about callback methods and callback events.
Callback methods
Overview
IMS supports the callback methods of HTTP requests and Simple Message Queue (SMQ) queues to obtain event notifications.
HTTP request: HTTP callbacks are automatically returned for you to obtain event notifications in IMS. You must deploy an HTTP service to receive callback messages and specify a callback URL in the IMS console or when you call an API operation. When an event is generated, IMS sends an HTTP POST request to the callback URL. The notification content is returned in the HTTP response body.
SMQ queue: You must manually obtain SMQ callbacks from IMS. You must authorize IMS to access SMQ, create a queue or use an existing queue in the SMQ console, and then configure the name of the SMQ queue in the IMS console or when you call an API operation. When an event is generated, IMS pushes the callback message to the queue. You need to view the received message in SMQ.
Comparison between callback methods
Item | HTTP request | SMQ queue |
Reliability | If the HTTP message receiving service is abnormal, messages may be lost. For example, messages may be lost if the service is interrupted or restarts. | The SMQ queue method is more reliable than the HTTP request method. Almost all SMQ callbacks succeed if they are configured properly. |
Security | If you use the HTTP request method, all users can send callback requests to the specified callback URL. However, you can use callback authentication to filter out invalid requests and enhance the security of the HTTP request method. For more information, see Callback authentication. | The SMQ queue method is more secure than the HTTP request method because only authorized users can read and write message queues. |
Convenience | The HTTP request method is more convenient than the SMQ queue method because you need to only deploy a message receiving service. | To use the SMQ queue method, you must activate and configure SMQ, and develop and deploy a program that consumes messages. |
Callback protocols
Callback method | Description |
HTTP request |
|
SMQ queue | Callback messages are in the JSON format. For more information about the sample message bodies and the corresponding parameter descriptions, see Event list. |
Callback determination and retries
Callback method | Callback result | Callback retry description |
HTTP request | After an HTTP request is sent, IMS checks the HTTP status code in the response returned by the HTTP message receiving service. If the HTTP status code 200 is returned, the callback is successful. If an HTTP status code other than 200 is returned or no response is returned within 3 seconds, the callback fails. IMS ignores the response body and determines whether the callback is successful only by HTTP status code. | If the callback request fails to be sent due to incorrect configurations, such as incorrect callback URL or a failure of the HTTP message receiving service, IMS retries to send the callback request two more times at an interval of 1 second. If the callback request fails to be sent after three attempts, IMS discards the request. |
SMQ queue | If you use the SMQ queue method, IMS determines that an SMQ callback is successful when the message is pushed to the SMQ queue. | If the message fails to be pushed to the queue due to incorrect configurations, IMS retries to push the message two more times at an interval of 1 second. For example, the callback message fails to be sent if IMS is not authorized to access SMQ, the queue endpoint is not a public endpoint, or the queue name is incorrect. If the message fails to be pushed after three attempts, IMS discards the message. |
We recommend that you use the SMQ queue method. The SMQ queue method is more reliable than the HTTP request method. Almost all SMQ callbacks succeed if they are configured properly.
Callback event types
IMS provides callback events related to features such as media asset upload, media processing, and online editing. You can configure specific callback events to obtain the task progress and status at the earliest opportunity. For more information, see Event list.