Callback Event Message Notification

Last updated: 2020-07-21 12:15:57

    After a push domain name is associated with a callback template, if an event configured in the template triggers the callback during a live streaming, Tencent Cloud will actively send a request to the customer server which is responsible for the response. After verification, a JSON packet of the callback can be obtained.
    Currently, the following events in a live streaming can trigger a notification:

    Note:

    This document does not cover the callback notification for porn detection events. For more information, see Best Practice - LVB Porn Detection.

    Prerequisites

    Event Message Notification Flow

    Overall process:

    1. The host configures an event message notification URL and related features such as recording and screencapturing in the console or through TencentCloud APIs.
    2. The host pushes or interrupts a stream.
    3. When an event occurs in the LVB service, a message will be sent to viewers via the event message notification service.

    Event Message Notification Configuration

    The event message notification can be configured with:

    Different event message notification URLs can be configured for different types of events, including:

    • Push event notification URL (StreamBeginNotifyUrl)
    • Stream interruption event notification URL (StreamEndNotifyUrl)
    • Recording event notification URL (RecordNotifyUrl)
    • Screencapturing event notification URL (SnapshotNotifyUrl)

    Event Message Notification Protocol

    Network protocol

    • Request: HTTP POST request with a JSON packet. The specific packet content of each type of message is described later.
    • Response: HTTP STATUS CODE = 200. The server ignores the specific content of the response packet. For more accurate connection, it is recommended to add JSON:{"code":0}`` to the response.

    Notification reliability

    The event notification service has a retry mechanism with an interval of 60 seconds for a total of 3 retries. In order to avoid the impact of retries on your server and network bandwidth, make sure that the response packet can be returned normally. A retry is triggered in the following cases:

    • No response packet is returned for a long time (at least 20 seconds).
    • The HTTP status code in the response is not 200.

    Event Message Notification Parameter Descriptions

    Common parameter description

    Field Name Type Description
    event_type int Event notification message type. 1: push event; 0: stream interruption event; 100: recording event; 200: screencapturing event
    sign string Event notification signature
    t int64 Event notification signature expiration time (UNIX timestamp)
    • t (expiration time): the default expiration time of a message notification from Tencent Cloud is 10 minutes. If the time specified by the t value in a message notification has elapsed, it can be determined that this notification is invalid, thereby preventing network replay attacks. The format of t is a decimal UNIX timestamp, i.e., the number of seconds that have elapsed since January 1, 1970 00:00 (UTC/GMT time).
    • sign (security signature): sign = MD5(key + t). Tencent Cloud splices the encryption key and t, calculates the sign value through MD5, and places it in the notification message. After your backend server receives the notification message, it can confirm whether the sign is correct based on the same algorithm and then determine whether the message is indeed from the Tencent Cloud backend.

      Note:

      key is the callback key in Feature Template > Callback Configuration, which is mainly used for authentication. In order to protect the security of your data, we recommend that you enter it.

    Message bodies in various types

    LVB push and stream interruption events

    • For an LVB push event, event\_type = 1
    • For an LVB stream interruption event, event\_type = 0
      Field NameTypeDescription
      appid int User `APPID`
      app string Push domain name
      appname string Push path
      stream_id string Live stream name
      channel_id string Same as the live stream name
      event_time int64 UNIX timestamp when the event message is generated
      sequence string Sequence number of the message, which indicates a push event. A push event generates push and stream interruption messages with the same sequence number.
      node string IP of the LVB access point
      user_ip string User's push IP
      stream_param string Parameters in the user's push URL
      push_duration string Push duration in the stream interruption event notification in milliseconds
      errcode int Stream interruption error codes
      errmsg string Description of stream interruption errors
    • errcode (stream interruption error codes)
      Error CodeDescriptionReason
      1 recv rtmp deleteStream The host actively interrupted the stream
      2 recv rtmp closeStream The host actively interrupted the stream
      3 recv() return 0 The host actively closed the TCP connection
      4 recv() return error Exception with the TCP connection to the host
      7 rtmp message large than 1M Exception with the received stream data
      Others LVB service internal exception If you need help, contact your Tencent Cloud sales rep or submit a ticket

    Sample:

    {
    "app":"test.domain.com",
    
    "appid":12345678,
    
    "appname":"live",
    
    "channel_id":"test_stream",
    
    "errcode":0,
    
    "errmsg":"ok",
    
    "event_time":1545115790,
    
    "event_type":1,
    
    "node":"100.121.160.92",
    
    "sequence":"6674468118806626493",
    
    "stream_id":"test_stream",
    
    "stream_param":"stream_param=test",
    
    "user_ip":"119.29.94.245",
    
    "sign":"ca3e25e5dc17a6f9909a9ae7281e300d",
    
    "t":1545030873
    }

    LVB recording file generation event

    • event_type = 100
      Field NameTypeDescription
      appid int User `APPID`
      stream_id string Live stream name
      channel_id string Same as the live stream name
      file_id string VOD file ID, which uniquely identifies a VOD file in the VOD system
      file_format string flv, hls, mp4, aac
      start_time int64 Start timestamp of the recording file
      end_time int64 End timestamp of the recording file
      duration int64 Recording file duration in seconds
      file_size uint64 Recording file size in bytes
      stream_param string Parameters in the user's push URL
      video_url string Recording file download URL

    Sample:

    {
    "event_type":100,
    
    "appid":12345678,
    
    "stream_id":"stream_test",
    
    "channel_id":"stream_test",
    
    "file_id":"1234567890",
    
    "file_format":"hls",
    
    "start_time":1545047010,
    
    "end_time":1545049971,
    
    "duration":2962,
    
    "file_size":277941079,
    
    "stream_param":"stream_param=test",
    
    "video_url":"http://12345678.vod2.myqcloud.com/xxxx/yyyy/zzzz.m3u8",
    
    "sign":"ca3e25e5dc17a6f9909a9ae7281e300d",
    
    "t":1545030873
    }

    LVB screenshot file generation event

    • event_type = 200
      Field NameTypeDescription
      stream_id string Live stream name
      channel_id string Same as the live stream name
      create_time int64 UNIX timestamp when the screenshot is generated
      file_size int Screenshot file size in bytes
      width int Screenshot width in pixels
      height int Screenshot height in pixels
      pic_url string Screenshot file path: /path/name.jpg.
      pic_full_url string Screenshot download URL

    Sample:

    {
    "event_type":200,
    
    "stream_id":"stream_name",
    
    "channel_id":"stream_name",
    
    "create_time":1545030273,
    
    "file_size":7520,
    
    "width":640,
    
    "height":352,
    
    "pic_url":"/2018-12-17/stream_name-screenshot-19-06-59-640x352.jpg",
    
    "pic_full_url":"http://testbucket-1234567890.cos.region.myqcloud.com/2018-12-17/stream_name-screenshot-19-06-59-640x352.jpg",
    
    "sign":"ca3e25e5dc17a6f9909a9ae7281e300d",
    
    "t":1545030873
    }

    Was this page helpful?

    Was this page helpful?

    • Not at all
    • Not very helpful
    • Somewhat helpful
    • Very helpful
    • Extremely helpful
    Send Feedback
    Help