Visionular

Live Event Notifications

AuroraLive supports event notifications, to let your application know when things happen asynchronously, outside of an API request cycle. For example, you may want to update something on your end when a live stream starts or is interrupted.

When these asynchronous events happen, we'll make a POST request to the address you give us and you can do whatever you need with it on your end.

Configuring Event Notifications

Event Notify is configured in the console under " Live Event Notifications".

stream_create
  • URL to notify: Enter a URL from your application that AuroraLive will call for event notifications.. (Maximum length: 256 characters)

Receiving events

AuroraLive will submit a POST request to the configured URL, which your application can treat the same as any other route. Your event handler can do things like update the state of the specified asset in your database, or trigger other work.

The event notify has a retry mechanism, up to 10 retries will be made at an interval of 1 minute.

A retry is triggered in the following cases:

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

Example Request

header:
AuroraLive-Signature: t=1659685897&sign=bb42114db71d8aa1bd361bd6ea1eaae631465c2991afde559cc6a724871b3d28


body:
{"push_time":1659685897,"live_stream_id":"Zjc0NjU3YmRiOWUxYzQyYmU1MGUzNmIwNGExNDkzNmE","event_type":"push"}
header:
AuroraLive-Signature: t=1659684548&sign=e8f0afc48ee03faf91a0ff3859c7bd67fc4868417bdc1620bfb19291ada930c1


body:
{"push_time":1659684531,"interruption_time":1659684548,"live_stream_id":"MDdjYzg5MmFhNTA0MjdkN2Q0YjY4ZmE1NDY3ODUzOTg","event_type":"interruption"}

Verify event notify signatures

You have the option to verify event notification requests that AuroraLive sends to your endpoints. AuroraLive will include a signature in the request's header. You can use this signature in your code to make sure the request was sent by AuroraLive and not a third party.

AuroraLive-Signature: t=1659608231&sign=1005d2c384a0f9739fae2532f446342dfc4406bd5dd0310b633c26c66fda152b

Event notifications contain a header called auroraLive-signature with the timestamp and a signature. The timestamp is prefixed by t= and the signature is prefixed by sign=. AuroraLive generates signatures using HMAC with SHA2-256.

1.Extract the timestamp and signature
Split the header at the & character and get the values for t (timestamp) and sign (the signature)

2.Prepare the signed_payload string
You will need:

  • the timestamp from Step 1 as a string (for example: "1659608231")
  • the character &
  • the raw request body (this will be JSON in a string format)

3.Determine the expected signature
Use the 3 components from Step 2 to compute an HMAC with the SHA256 hash function. Depending on the language that you are using this will look something like the following:

signKey  = 'Your Signing Key' // You custom a Signing Key When you configure event notify.
payload = timestamp + "&" + request_body
expected_signature = createHmacSha256(payload, signKey)

4.Compare signature
Compare the signature in the header to the expected signature.

Examples Golang

func IsValidSignature(req *http.Request, body []byte) error {
    signature := req.Header.Get("AuroraLive-Signature")


    if signature == "" {
       return errors.New("no AuroraLive-Signature in request header")
    }


    signArr := strings.Split(signature, "&")


    if len(signArr) != 2 {
       return errors.New(fmt.Sprintf("AuroraLive-Signature in request header should be two values long: %s", signArr))
    }


    timestampArr := strings.Split(signArr[0], "=")
    signInfoArr := strings.Split(signArr[1], "=")


    if len(timestampArr) != 2 || len(signArr) != 2 {
        return errors.New(fmt.Sprintf("missing timestamp: %s or missing signature: %s", timestampArr, signArr))
    }


    timestamp := timestampArr[1]
    signInfo := signInfoArr[1]


    signKey := "sign_key"
    sign := getSign(signKey, timestamp, body)


    if sign != signInfo {
        return errors.New("not a valid AuroraLive-Signature")
    }


    return nil
}


func getSign(signKey, timestamp string, body []byte) string {
    payload := fmt.Sprintf("%s&%s", timestamp, string(body))
    h := hmac.New(sha256.New, []byte(signKey))
    h.Write([]byte(payload))
   
    return hex.EncodeToString(h.Sum(nil))
}

Types of Events

Live Stream Events

  • created: A new live stream has been created. Broadcasters with a stream_key can start sending encoder feed to this live stream.
  • connected: An encoder has successfully connected to this live stream.
  • recording: Recording on this live stream has started. AuroraCloud Live has successfully processed the first frames from the encoder. If you show a red dot icon in your UI, this would be a good time to show it.
  • active: This live stream is now "active". The live streams playback_id OR the playback_id associated with this live stream's asset can be used right now to created HLS URLs (https://stream.visionular.com/{PLAYBACK_ID}.m3u8 and start streaming in your player. Note that before the live stream is "active", trying to stream the HLS URL will result in HTTP 412 errors.
  • disconnected: An encoder has disconnected from this live stream. Note that while disconnected the live stream is still status: "active".
  • idle: The reconnect_window for this live stream has elapsed. The live stream status will now transition to "idle".
  • updated: This live stream has been updated. For example, after resetting the live stream's stream key API.
  • enabled: This live stream has been enabled. This event fires after enable live stream API.
  • disabled: This live stream has been disabled. This event fires after disable live stream API. Disabled live streams will no longer accept new RTMP connections.
  • deleted: This live stream has been deleted. This event fires after delete live stream API.

Simulcast Target Events

These simulcast target events are useful when creating a UI that shows your users the status of their configured 3rd party endpoints. These events are handy when you want to build a UI that shows the state of each simulcast target and keep track of the state changes as they happen.

  • simulcast_target.created: A new simulcast target has been created for this live stream.
  • simulcast_target.idle: When the parent live stream is "disconnected", all simulcast targets will have be "idle".
  • simulcast_target.active: When the parent live stream fires "connected" then the simulcast targets transition to "active".
  • simulcast_target.deleted: This simulcast target has been deleted.

Example Response

{
    "type": "disabled",
    "id": "adc1d50f-9a25-f032-0be8-f2280f243967",
    "data": {
        "stream_key": "b28edd57-2091-ca2f-7ec4-dd0a43b19c34",
        "status": "disabled",
        "reconnect_window": 60,
        ...
        "max_continuous_duration": 43200,
        "latency_mode": "standard",
        "id": "3dDAFFK9vJQdVZMqDBIOh8PChlcNt02fEWM02XicGSXjs",
        "created_at": 1699950576
    },
    "created_at": "2023-11-20T06:39:01.047000Z"
}
11/26/2024 11:48:04