Documentation
Server APIs v2
Server callbacks
Callback on stream mixing ended

Callback on stream mixing ended

Last updated：2024-08-08 17:33

1 Description

For your app server to receive callbacks from the ZEGOCLOUD server, you need to set up server-to-server callbacks first.

When a stream mixing task on a stream mixing server ends, the stream mixing server notifies your app server by sending a POST request to the pre-configured callback endpoint.

When the following situations occur:

When the processing of the end of the mixing fails and there is no callback.
When the mixing process is terminated abnormally and there is no callback.

2 Callback request

Request method: POST.
Request endpoint: the callback address provided by you, which is maintained in the ZEGOCLOUD Admin Console.
Transmission protocol: HTTPS
- The callback data needs to be decoded by UrlDecode.
- When using the POST request method to pass parameters:
  - The parameters in the body can be directly passed in the JsonObject format, without the need to serialize them into a string format.
  - In the headers, set "Content-type" to "application/json".

Request address: Please contact ZEGOCLOUD technical support to configure the callback address.
Transmission protocol: HTTPS/HTTP, it is recommended to use HTTPS.
3 Callback parameters

Parameter	Type	Description
appid	String	App identifier.
event	String	Event name. For this callback, the event name is "mix_stop".
seq	String	The sequence number of the stream mixing request, which guarantees the requests to be executed in the correct order. It increases by one each time.
task_id	String	Task ID of the stream mixing task. If you specify the task_id in the request that starts the stream mixing task, ZEGOCLOUD adds your AppID as a prefix to the task_id to form a new task ID. If you don't specify the task_id in the request, ZEGOCLOUD generates a task ID by concatenating other parameters, such as mix_url and others.
channel_id	String	Channel ID, with a maximum length of 255 bytes. It's equivalent to the Room ID on the client side.
publish_id	String	Publisher ID, with a maximum length of 255 bytes. It's equivalent to the User ID on the client side.
mix_url	String	The URL of the output stream (for RTMP streaming), with a maximum length of 255 bytes.
mix_stream_alias	String	The stream ID of the output stream, with a maximum length of 255 bytes.
timestamp	String	The current time of the server, a Unix timestamp.
nonce	String	Random number.
signature	String	Signature string for authentication. For more details about the request signature, see Authenticating server-to-server callbacks.

It is recommended that you convert some parameters to Int for logical processing. The relevant fields include appid, seq, and timestamp.

4 Sample request data

 {
    "appid": "111111",
     "channel_id": "2222",
    "event": "mix_stop",
     "mix_stream_alias": "aaa",
     "mix_url": "rtmp://rtmp.wsdemo.zego.im/zegodemo/aaa",
     "nonce": "7257787020413449571",
    "publish_id": "abc",
     "seq": "1234",
     "signature": "fadc2c4abb5714c30a711b3ad6f7783e37531263",
     "task_id": "111111:1111",
     "timestamp": "1689835223"
 }

5 Response

Returning an HTTP status code of 2XX (e.g. 200) indicates success, while other responses indicate failure.

6 Callback Retry Strategy

If the ZEGOCLOUD server does not receive a response, or the HTTP status code received by the ZEGOCLOUD server is not 2xx (such as 200), it will retry with intervals of 2s, 4s, 8s, 16s, and 32s respectively. If the retry still fails after an interval of 32s, it will no longer retry.