Skip to main content
  • Core Products
  • Add-Ons
  • Extensions Marketplace

    Receive event notifications

    A webhook is a user-defined callback over HTTP. You use webhooks to notify your app or back-end system when certain Media Push events occur. Agora Notifications enables you to subscribe to events and receive notifications about them across multiple product lines.

    Understand the tech​

    Using Agora Console you subscribe to specific events for your project and configure the URL of the webhooks to receive these events. Agora sends notifications of your events to your webhook every time they occur. Your server authenticates the notification and returns 200 Ok to confirm reception. You use the information in the JSON payload of each notification to give the best user experience to your users.

    The following figure illustrates the workflow when Notifications is enabled for the specific Media Push events you subscribe to:

    media-push

    1. A user commits an action that creates an event.
    2. Notifications sends an HTTPS POST request to your webhook.
    3. Your server validates the request signature, then sends a response to Notifications within 10 seconds. The response body must be in JSON.

    If Notifications receives 200 OK within 10 seconds of sending the initial notification, the callback is considered successful. If these conditions are not met, Notifications immediately resends the notification. The interval between notification attempts gradually increases. Notifications stops sending notifications after three retries.

    Prerequisites​

    To set up and use Notifications, you must have:

    Handle notifications for specific events​

    In order to handle notifications for the events you subscribe to, you need to:

    Create your webhook​

    Once Notifications is enabled, Agora SD-RTN™ sends notification callbacks as HTTPS POST requests to your webhook when events that you are subscribed to occur. The data format of the requests is JSON, the character encoding is UTF-8, and the signature algorithm is HMAC/SHA1 or HMAC/SHA256.

    For Notifications, a webhook is an endpoint on an HTTP server that handles these requests. In a production environment you write this in your web infrastructure, for development purposes best practice is to create a simple local server and use a service such as ngrok to supply a public URL that you register with Agora SD-RTN™ when you enable Notifications.

    To do this, take the following steps:

    1. Set up Go

      Ensure you have Go installed on your system. If not, download and install it from the official Go website.

    2. Create a Go project for your server

      Create a new directory for your project and navigate into it:


      _2
      mkdir agora-webhook-server
      _2
      cd agora-webhook-server

      In the project directory, create a new file main.go. Open the file in your preferred text editor and add the following code:


      _62
      package main
      _62
      _62
      import (
      _62
      "encoding/json"
      _62
      "fmt"
      _62
      "io"
      _62
      "log"
      _62
      "net/http"
      _62
      )
      _62
      _62
      type WebhookRequest struct {
      _62
      NoticeID string `json:"noticeId"`
      _62
      ProductID int64 `json:"productId"`
      _62
      EventType int `json:"eventType"`
      _62
      Payload Payload `json:"payload"`
      _62
      }
      _62
      _62
      type Payload struct {
      _62
      ClientSeq int64 `json:"clientSeq"`
      _62
      UID int `json:"uid"`
      _62
      ChannelName string `json:"channelName"`
      _62
      }
      _62
      _62
      func rootHandler(w http.ResponseWriter, r *http.Request) {
      _62
      response := `<h1>Agora Notifications demo</h1>`
      _62
      w.WriteHeader(http.StatusOK)
      _62
      w.Write([]byte(response))
      _62
      }
      _62
      _62
      func ncsHandler(w http.ResponseWriter, r *http.Request) {
      _62
      agoraSignature := r.Header.Get("Agora-Signature")
      _62
      fmt.Println("Agora-Signature:", agoraSignature)
      _62
      _62
      body, err := io.ReadAll(r.Body)
      _62
      if err != nil {
      _62
      http.Error(w, "Unable to read request body", http.StatusBadRequest)
      _62
      return
      _62
      }
      _62
      _62
      var req WebhookRequest
      _62
      if err := json.Unmarshal(body, &req); err != nil {
      _62
      http.Error(w, "Invalid JSON", http.StatusBadRequest)
      _62
      return
      _62
      }
      _62
      _62
      fmt.Printf("Event code: %d Uid: %d Channel: %s ClientSeq: %d\n",
      _62
      req.EventType, req.Payload.UID, req.Payload.ChannelName, req.Payload.ClientSeq)
      _62
      _62
      w.WriteHeader(http.StatusOK)
      _62
      w.Write([]byte("Ok"))
      _62
      }
      _62
      _62
      func main() {
      _62
      http.HandleFunc("/", rootHandler)
      _62
      http.HandleFunc("/ncsNotify", ncsHandler)
      _62
      _62
      port := ":8080"
      _62
      fmt.Printf("Notifications webhook server started on port %s\n", port)
      _62
      if err := http.ListenAndServe(port, nil); err != nil {
      _62
      log.Fatalf("Failed to start server: %v", err)
      _62
      }
      _62
      }

    3. Run your Go server

      Run the server using the following command:


      _1
      go run main.go

    4. Create a public URL for your server

      In this example you use ngrok to create a public URL for your server.

      1. Download and install ngrok. If you have Chocolatey, use the following command:


        _1
        choco install ngrok

      2. Add an authtoken to ngrok:


        _1
        ngrok config add-authtoken <authToken>

        To obtain an authToken, sign up with ngrok.

      3. Start a tunnel to your local server using the following command:


        _1
        ngrok http 127.0.0.1:8080

        You see a Forwarding URL and a Web Interface URL in the console. Open the web interface URL in your browser.

    5. Test the server

      Open a web browser and navigate to the public URL provided by ngrok to see the root handler response.

      Use curl, Postman, or another tool to send a POST request to https://<ngrok_url>/ncsNotify with the required JSON payload.

      Example using curl:


      _13
      curl -X POST <ngrok_url>/ncsNotify \
      _13
      -H "Content-Type: application/json" \
      _13
      -H "Agora-Signature: your_signature" \
      _13
      -d '{
      _13
      "noticeId": "some_notice_id",
      _13
      "productId": 12345,
      _13
      "eventType": 1,
      _13
      "payload": {
      _13
      "clientSeq": 67890,
      _13
      "uid": 123,
      _13
      "channelName": "test_channel"
      _13
      }
      _13
      }'

      Make sure you replace ngrok_url with the forwarding url.

      Once the HTTP request is successful, you see the following JSON payload in your browser:


      _10
      {
      _10
      "noticeId": "some_notice_id",
      _10
      "productId": 12345,
      _10
      "eventType": 1,
      _10
      "payload": {
      _10
      "clientSeq": 67890,
      _10
      "uid": 123,
      _10
      "channelName": "test_channel"
      _10
      }
      _10
      }

    Enable Notifications​

    To enable Notifications:

    1. Log in to Agora Console. On the Projects tab, locate the project for which you want to enable Notifications and click Configure.

    2. In the Features section, locate Notifications, and click Enable.

    3. On the configuration page, click on the service for which you want to enable notifications. The item expands to show configuration options.

    4. Fill in the following information:

      • Event: Select all the events that you want to subscribe to.

        If the selected events generate a high number of queries per second (QPS), ensure that your server has sufficient processing capacity.

      • Receiving Server Region: Select the region where your server that receives the notifications is located. Agora connects to the nearest Agora node server based on your selection.

      • Receiving Server URL Endpoint: The HTTPS public address of your server that receives the notifications. For example, https://1111-123-456-789-99.ap.ngrok.io/ncsNotify.

        info

        For enhanced security, Notifications no longer supports HTTP addresses.

        • To reduce the delay in notification delivery, best practice is to activate HTTP persistent connection (also called HTTP keep-alive) on your server with the following settings:

          • MaxKeepAliveRequests: 100 or more
          • KeepAliveTimeout: 10 seconds or more

      • Whitelist: If your server is behind a firewall, check the box here, and ensure that you call the IP address query API to get the IP addresses of the Agora Notifications server and add them to the firewall's allowed IP list.

    5. Copy the Secret displayed against the product name by clicking the copy icon. You use this secret to Add signature verification.

    6. Press Save. Agora performs a health test for your configuration as follows:

      1. The Notifications health test generates test events that correspond to your subscribed events, and then sends test event callbacks to your server.

      2. After receiving each test event callback, your server must respond within 10 seconds with a status code of 200. The response body must be in JSON format.

      3. When the Notifications health test succeeds, read the prompt and press Save Notifications Configuration. After your configuration is saved, the Status of Notifications shows Enabled.

        If the Notifications health test fails, follow the prompt on the Agora Console to troubleshoot the error. Common errors include the following:

        • Request timeout (590): Your server does not return the status code 200 within 10 seconds. Check whether your server responds to the request properly. If your server responds to the request properly, contact Agora Technical Support to check if the network connection between the Agora Notifications server and your server is working.

        • Domain name unreachable (591): The domain name is invalid and cannot be resolved to the target IP address. Check whether your server is properly deployed.

        • Certificate error (592): The Agora Notifications server fails to verify the SSL certificates returned by your server. Check if the SSL certificates of your server are valid. If your server is behind a firewall, check whether you have added all IP addresses of the Agora Notifications server to the firewall's allowed IP list.

        • Other response errors: Your server returns a response with a status code other than 200. See the prompt on the Agora Console for the specific status code and error messages.

    Add signature verification​

    To communicate securely between Notifications and your webhook, Agora SD-RTN™ uses signatures for identity verification as follows:

    1. When you configure Notifications in Agora Console, Agora SD-RTN™ generates a secret you use for verification.

    2. When sending a notification, Notifications generates two signature values from the secret using HMAC/SHA1 and HMAC/SHA256 algorithms. These signatures are added as Agora-Signature and Agora-Signature-V2 to the HTTPS request header.

    3. When your server receives a callback, you can verify Agora-Signature or Agora-Signature-V2:

      • To verify Agora-Signature, use the secret, the raw request body, and the crypto/sha1 algorithm.
      • To verify Agora-Signature-V2, use the secret, the raw request body, and the crypto/sha256 algorithm.

    The following sample code uses crypto/sha1.

    To add signature verification to your server, take the following steps:

    1. In the main.go file, replace your imports with with the following:


      _10
      import (
      _10
      "crypto/hmac"
      _10
      "crypto/sha1"
      _10
      "encoding/hex"
      _10
      "encoding/json"
      _10
      "fmt"
      _10
      "io"
      _10
      "log"
      _10
      "net/http"
      _10
      )

    2. Add the following code after the list of imports:


      _17
      // Replace with your NCS secret
      _17
      const secret = "<Replace with your secret code>"
      _17
      _17
      // calcSignatureV1 computes the HMAC/SHA256 signature for a given payload and secret
      _17
      func calcSignatureV1(secret, payload string) string {
      _17
      mac := hmac.New(sha1.New, []byte(secret))
      _17
      mac.Write([]byte(payload))
      _17
      return hex.EncodeToString(mac.Sum(nil))
      _17
      }
      _17
      _17
      // verify checks if the provided signature matches the HMAC/SHA256 signature of the request body
      _17
      func verify(requestBody, signature string) bool {
      _17
      calculatedSignature := calcSignatureV1(secret, requestBody)
      _17
      fmt.Println("Calculated Signature:", calculatedSignature)
      _17
      fmt.Println("Received Signature:", signature)
      _17
      return calculatedSignature == signature
      _17
      }

    3. In the main.go file, add the following code after fmt.Println("Request Body:", string(body)):


      _5
      // Verify the signature
      _5
      if !verify(string(body), agoraSignature) {
      _5
      http.Error(w, "Invalid signature", http.StatusUnauthorized)
      _5
      return
      _5
      }

    4. To test the server, follow the steps given in the Enable notifications section.

    5. When you receive an event from the console, and if the signature matches, the event details are displayed in your browser.

    Reference​

    This section contains in depth information about Notifications.

    Request Header​

    The header of notification callbacks contains the following fields:

    Field nameValue
    Content-Typeapplication/json
    Agora-SignatureThe signature generated by Agora using the Secret and the HMAC/SHA1 algorithm. You need to use the Secret and HMAC/SHA1 algorithm to verify the signature value. For details, see Signature verification.
    Agora-Signature-V2The signature generated by Agora using the Secret and the HMAC/SHA256 algorithm. You need to use the Secret and the HMAC/SHA256 algorithm to verify the signature value. For details, see Signature verification.

    Request Body​

    The request body of notification callbacks contains the following fields:

    Field nameTypeDescription
    noticeIdStringThe notification ID, identifying the notification callback when the event occurs.
    productIdNumberThe product ID:
    • 1: Realtime Communication (RTC) service
    • 3: Cloud Recording
    • 4: Media Pull
    • 5: Media Push
    eventTypeNumberThe type of event being notified. For details, see event types.
    notifyMsNumberThe Unix timestamp (ms) when Notifications sends a callback to your server. This value is updated when Notifications resends the notification callback.
    payloadJSON ObjectThe content of the event being notified. The payload varies with event type.

    Example​


    _9
    {
    _9
    "noticeId":"2000001428:4330:107",
    _9
    "productId":1,
    _9
    "eventType":101,
    _9
    "notifyMs":1611566412672,
    _9
    "payload":{
    _9
    ...
    _9
    }
    _9
    }

    Event types​

    Notifications can notify your server of the following events when pushing media streams to the CDN:

    eventTypeEvent nameDescription
    1Converter createdA Converter is created by calling the Create method
    2Converter configuration changedThe configuration of the Converter changed.
    3Converter status changedRunning state of the Converter changed.
    4Converter destroyedConverter is destroyed, and the streams being pushed to the CDN are stopped.

    Converter created​

    Notifications notifies your server of this event when you create a converter by calling the Create method.

    The eventType is1 (Converter Created). The following is an example the payload:


    _70
    {
    _70
    "converter": {
    _70
    "id": "4c014467d647bb87b60b719f6fa57686",
    _70
    "name": "show68_vertical",
    _70
    "transcodeOptions": {
    _70
    "rtcChannel": "show68",
    _70
    "audioOptions": {
    _70
    "codecProfile": "HE-AAC",
    _70
    "sampleRate": 48000,
    _70
    "bitrate": 128,
    _70
    "audioChannels": 1,
    _70
    "rtcStreamUids": [
    _70
    201,
    _70
    202
    _70
    ]
    _70
    },
    _70
    "videoOptions": {
    _70
    "canvas": {
    _70
    "width": 360,
    _70
    "height": 640,
    _70
    "color": 0
    _70
    },
    _70
    "layout": [
    _70
    {
    _70
    "rtcStreamUid": 201,
    _70
    "region": {
    _70
    "xPos": 0,
    _70
    "yPos": 0,
    _70
    "zIndex": 1,
    _70
    "width": 360,
    _70
    "height": 320
    _70
    },
    _70
    "placeholderImageUrl": "http://example.agora.io/host_placeholder.jpg"
    _70
    },
    _70
    {
    _70
    "rtcStreamUid": 202,
    _70
    "region": {
    _70
    "xPos": 0,
    _70
    "yPos": 320,
    _70
    "zIndex": 1,
    _70
    "width": 360,
    _70
    "height": 320
    _70
    }
    _70
    },
    _70
    {
    _70
    "imageUrl": "http://example.agora.io/watchmark.jpg",
    _70
    "region": {
    _70
    "xPos": 0,
    _70
    "yPos": 0,
    _70
    "zIndex": 2,
    _70
    "width": 36,
    _70
    "height": 64
    _70
    }
    _70
    }
    _70
    ],
    _70
    "codecProfile": "High",
    _70
    "frameRate": 15,
    _70
    "bitrate": 400,
    _70
    "seiOptions": ""
    _70
    }
    _70
    },
    _70
    "rtmpUrl": "rtmp://example.agora.io/live/show68",
    _70
    "idleTimeout": 300,
    _70
    "createTs": 1591786766,
    _70
    "updateTs": 1591786835,
    _70
    "state": "connecting"
    _70
    },
    _70
    "lts": 1603456600,
    _70
    "xRequestId": "7bbcc8a4acce48c78b53c5a261a8a564"
    _70
    }

    • The Converter contains the following fields:
      • id: String type field. The ID of the Converter. This is a UUID (Universal Unique Identifier) generated by the Agora server to identify a created Converter.
      • name: String type field. The name of the Converter.
      • transcodeOptions: JSON Object type field. The Converter's transcoding configuration.
        • rtcChannel: String type field. The Agora channel name.
        • audioOptions: JSON Object type field. The audio transcoding configuration of the Converter.
          • codecProfile: String type field. The audio codec output by the Converter.
          • sampleRate: Number type field. The audio encoding sampling rate (Hz) output by the Converter.
          • bitrate: Number type field. The audio encoding rate (Kbps) output by the Converter.
          • audioChannels: Number type field. The number of audio channels output by the Converter.
          • rtcStreamUids: JSON Array type field. The user ID or Account of the user participating in the mixing.
        • videoOptions: JSON Object type field. The video transcoding configuration of the Converter.
          • canvas: JSON Object type field. The video canvas.
            • width: Number type field. The width of the canvas (px).
            • height: Number type field. The height of the canvas (px).
            • color: Number type field. The background color of the canvas. This is an RGB color value, expressed as a decimal number. For example, 255 represents blue.
          • layout: JSON Array type field. The content description of the video screen on the canvas. Two elements are supported:
            • RtcStreamView element. The video screen of each user on the canvas. It contains the following fields:
              • rtcStreamUid: Number type field. The user ID of the user to which the video stream belongs.
              • region: JSON Object type field. The display area of the user's video screen on the canvas.
                • xPos: Number type field. The x coordinate (px) of the screen on the canvas. This is the lateral displacement relative to the origin, taking the upper left corner of the canvas as the origin and the x coordinate as the upper left corner of the screen.
                • yPos: Number type field. The y coordinate (px) of the screen on the canvas. This is the longitudinal displacement relative to the origin, taking the upper left corner of the canvas as the origin and the y coordinate as the upper left corner of the screen.
                • zIndex: Number type field. The layer number of the screen. The value range is [0,100]. 0 represents the lowest layer. 100 represents the top layer.
                • width: Number type field. The width of the screen (px).
                • height: Number type field. The height of the screen (px).
              • placeholderImageUrl: String type field. The HTTP(S) URL of the substitute image.
            • ImageView element. The video picture on the canvas, which can be used as a watermark. It contains the following fields:
              • imageUrl: String type field. The HTTP(S) URL of the image.
              • region: JSON Object type field. The display area of the picture on the canvas.
                • xPos: Number type field. The x coordinate (px) of the image on the canvas. This is the lateral displacement relative to the origin, taking the upper left corner of the canvas as the origin and the x coordinate as the upper left corner of the screen.
                • yPos: Number type field. The y coordinate (px) of the picture on the canvas. This is the longitudinal displacement relative to the origin, taking the upper left corner of the canvas as the origin, and the y coordinate as the upper left corner of the screen.
                • zIndex: Number type field. The layer number of the image. The value range is [0,100]. 0 represents the lowest layer. 100 represents the top layer.
                • width: Number type field. The width of the image (px).
                • height: Number type field. The height of the image (px).
          • codecProfile: String type field. The encoding specification of the video.
          • frameRate: Number type field. The encoding frame rate (fps) of the video.
          • bitrate: Number type field. The audio encoding rate (Kbps) output by the Converter.
          • seiExtraInfo: String type field. The user SEI information in the video. This is used to send user-defined SEI information to the CDN.
        • rtmpUrl: (Required) String type field. The CDN streaming address.
        • idleTimeOut: Number type field. The maximum time (s) that the Converter is idle. Idle means that all users of the corresponding media streams processed by the Converter have left the channel. After the idle state exceeds the set idleTimeOut, the Converter is destroyed automatically.
        • createTs: Number type field. The Unix timestamp (s) when the Converter was created.
        • updateTs: Number type field. The Unix timestamp (s) when the Converter configurationwas last updated.
        • state: String type field. The status of the Converter. If if the state is reported "connecting", the Converter is connecting to the Agora server.
    • lts: Number type field. The Unix timestamp (ms) when the event occurred on the Agora server.
    • xRequestId: String type field, which identifies the UUID (Universal Unique Identifier) of this request. This is the same as the X-Request-ID field in the request header.

    Converter configuration changed​

    Notifications notifies your server of this event when you update the configurations of a Converter by calling the Update method.

    The eventType is 2 (ConverterUpdatedEvent).

    • Update the converter.transcodeOptions.videoOptions.layout configuration. The following is an example payload:


      _53
      {
      _53
      "converter": {
      _53
      "id": "4c014467d647bb87b60b719f6fa57686",
      _53
      "createTs": 1591786766,
      _53
      "updateTs": 1591786835,
      _53
      "state": "running",
      _53
      "transcodeOptions": {
      _53
      "rtcChannel": "show68",
      _53
      "videoOptions": {
      _53
      "layout": [
      _53
      {
      _53
      "rtcStreamUid": 201,
      _53
      "region": {
      _53
      "xPos": 0,
      _53
      "yPos": 0,
      _53
      "zIndex": 1,
      _53
      "width": 360,
      _53
      "height": 320
      _53
      },
      _53
      "placeholderImageUrl": "http://example.agora.io/host_placeholder.jpg"
      _53
      },
      _53
      {
      _53
      "rtcStreamUid": 202,
      _53
      "region": {
      _53
      "xPos": 0,
      _53
      "yPos": 320,
      _53
      "zIndex": 1,
      _53
      "width": 360,
      _53
      "height": 320
      _53
      }
      _53
      },
      _53
      {
      _53
      "imageUrl": "http://example.agora.io/watchmark.jpg",
      _53
      "region": {
      _53
      "xPos": 0,
      _53
      "yPos": 0,
      _53
      "zIndex": 2,
      _53
      "width": 36,
      _53
      "height": 64
      _53
      }
      _53
      }
      _53
      ],
      _53
      "codecProfile": "High",
      _53
      "frameRate": 15,
      _53
      "bitrate": 400,
      _53
      "seiOptions": ""
      _53
      }
      _53
      }
      _53
      },
      _53
      "lts": 1603456600,
      _53
      "xRequestId": "7bbcc8a4acce48c78b53c5a261a8a564",
      _53
      "fields": "id,createTs,updateTs,state,transcodeOptions.videoOptions.layout"
      _53
      }

      • The Converter contains the following fields:
        • id: String type field. The ID of the Converter. This is a UUID (Universal Unique Identifier) generated by the Agora server to identify a created Converter.
        • createTs: Number type field. The Unix timestamp (s) when the Converter was created.
        • updateTs: Number type field. The Unix timestamp (s) when the Converter configurationwas last updated.
        • state: String type field. The running status of the Converter. If the state is "running", the Converter is running properly, and streams are being pushed to the CDN.
        • transcodeOptions: JSON Object type field. The Converter's transcoding configuration.
          • rtcChannel: String type field. The Agora channel name.
          • videoOptions: (Optional) JSON Object type field. The video transcoding configuration of the Converter.
            • layout: JSON Array type field. The content description of the video screen on the canvas. Two elements are supported:
              • RtcStreamView element. The video screen of each user on the canvas. It contains the following fields:
                • rtcStreamUid: Number type field. The user ID of the user to which the video stream belongs.
                • region: JSON Object type field. The display area of the user's video screen on the canvas.
                  • xPos: Number type field. The x coordinate (px) of the screen on the canvas. This is the lateral displacement relative to the origin, taking the upper left corner of the canvas as the origin and the x coordinate as the upper left corner of the screen.
                  • yPos: Number type field. The y coordinate (px) of the screen on the canvas. This is the longitudinal displacement relative to the origin, taking the upper left corner of the canvas as the origin and the y coordinate as the upper left corner of the screen.
                  • zIndex: Number type field. The layer number of the screen. The value range is [0,100]. 0 represents the lowest layer. 100 represents the top layer.
                  • width: Number type field. The width of the screen (px).
                  • height: Number type field. The height of the screen (px).
                • placeholderImageUrl: String type field. The HTTP(S) URL of the substitute image.
              • ImageView element. The video picture on the canvas, which can be used as a watermark. It contains the following fields:
                • imageUrl: String type field. The HTTP(S) URL of the image.
                • region: JSON Object type field. The display area of the picture on the canvas.
                  • xPos: Number type field. The x coordinate (px) of the image on the canvas. This is the lateral displacement relative to the origin, taking the upper left corner of the canvas as the origin and the x coordinate as the upper left corner of the screen.
                  • yPos: Number type field. The y coordinate (px) of the picture on the canvas. This is the longitudinal displacement relative to the origin, taking the upper left corner of the canvas as the origin, and the y coordinate as the upper left corner of the screen.
                  • zIndex: Number type field. The layer number of the image. The value range is [0,100]. 0 represents the lowest layer. 100 represents the top layer.
                  • width: Number type field. The width of the image (px).
                  • height: Number type field. The height of the image (px).
          • codecProfile: String type field. The encoding specification of the video.
          • frameRate: Number type field. The encoding frame rate (fps) of the video.
          • bitrate: Number type field. The encoding bitrate (Kbps) of the video.
          • seiExtraInfo: String type field. The user SEI information in the video. This is used to send user-defined SEI information to the CDN.
      • lts: Number type field. The Unix timestamp (ms) when the event occurred on the Agora server.
      • xRequestId: String type field, which identifies the UUID (Universal Unique Identifier) of this request. This is the same as the X-Request-ID field in the request header.
      • fields: String type field. For the field mask of JSON encoding, please refer to the Google protobuf FieldMask document for details. This is used to specify a subset of theconverter field to be returned. In this example, fields specifies a subset of the id, createTs, updateTs, and state fields in the converter field returned by the Agora server.

    • Update the configuration of the list of user IDs or Accounts participating in the mixing in the converter.transcodeOptions.audioOptions. The following is an example payload:


      _20
      {
      _20
      "converter": {
      _20
      "id": "4c014467d647bb87b60b719f6fa57686",
      _20
      "createTs": 1591786766,
      _20
      "updateTs": 1591786835,
      _20
      "state": "running",
      _20
      "transcodeOptions": {
      _20
      "rtcChannel": "show68",
      _20
      "audioOptions": {
      _20
      "rtcStreamUids": [
      _20
      201,
      _20
      202
      _20
      ]
      _20
      }
      _20
      }
      _20
      },
      _20
      "lts": 1603456600,
      _20
      "xRequestId": "7bbcc8a4acce48c78b53c5a261a8a564",
      _20
      "fields": "id,createTs,updateTs,state,transcodeOptions.audioOptions.rtcStreamUids"
      _20
      }

      • The Converter contains the following fields:
        • id: String type field. The ID of the Converter. This is a UUID (Universal Unique Identifier) generated by the Agora server to identify a created Converter.
        • createTs: Number type field. The Unix timestamp (s) when the Converter was created.
        • updateTs: Number type field. The Unix timestamp (s) when the Converter configurationwas last updated.
        • state: String type field. The running status of the Converter. If the state is "running", the Converter is running properly, and streams are being pushed to the CDN.
        • transcodeOptions: JSON Object type field. The Converter's transcoding configuration.
          • rtcChannel: String type field. The Agora channel name.
          • audioOptions: JSON Object type field. The audio transcoding configuration of the Converter.
            • rtcStreamUids: JSON Array type field. The user ID or Account of the user participating in the mixing.
      • lts: Number type field. The Unix timestamp (ms) when the event occurred on the Agora server.
      • xRequestId: String type field, which identifies the UUID (Universal Unique Identifier) of this request. This is the same as the X-Request-ID field in the request header.
      • fields: String type field. For the field mask of JSON encoding, please refer to the Google protobuf FieldMask document for details. This is used to specify a subset of theconverter field to be returned. In this example, fields specifies a subset of the id, createTs, updateTs, and statefields in the converter field returned by the Agora server.

    • Update other configurations of the converter, such as converter.rtmpUrl:


      _12
      {
      _12
      "converter": {
      _12
      "id": "4c014467d647bb87b60b719f6fa57686",
      _12
      "createTs": 1591786766,
      _12
      "updateTs": 1591786835,
      _12
      "state": "running",
      _12
      "rtmpUrl": "rtmp://example.agora.io/live/show68"
      _12
      },
      _12
      "lts": 1603456600,
      _12
      "xRequestId": "7bbcc8a4acce48c78b53c5a261a8a564",
      _12
      "fields": "id,createTs,updateTs,state,rtmpUrl"
      _12
      }

      • The Converter contains the following fields:
        • id: String type field. The ID of the Converter. This is a UUID (Universal Unique Identifier) generated by the Agora server to identify a created Converter.
        • createTs: Number type field. The Unix timestamp (s) when the Converter was created.
        • updateTs: Number type field. The Unix timestamp (s) when the Converter configurationwas last updated.
        • state: String type field. The running status of the Converter. If the state is "running", the Converter is running properly, and streams are being pushed to the CDN.
        • rtmpUrl: (Required) String type field. The CDN streaming address.
      • lts: Number type field. The Unix timestamp (ms) when the event occurred on the Agora server.
      • xRequestId: String type field, which identifies the UUID (Universal Unique Identifier) of this request. This is the same as the X-Request-ID field in the request header.
      • fields: String type field. For the field mask of JSON encoding, please refer to the Google protobuf FieldMask document for details. This is used to specify a subset of theconverter field to be returned. In this example, fields specifies a subset of the id, createTs, updateTs, and state fields in the converter field returned by the Agora server.

    Converter status changed​

    Notifications notifies your server of this event when you have created a Converter and the running state of the Converter changes.

    The eventType is 3(ConverterStateChangedEvent). The following is an example payload:


    _10
    {
    _10
    "converter": {
    _10
    "id": "4c014467d647bb87b60b719f6fa57686",
    _10
    "createTs": 1603456600,
    _10
    "updateTs": 1603456600,
    _10
    "state": "running"
    _10
    },
    _10
    "lts": 1603456600,
    _10
    "fields": "id,createTs,updateTs,state"
    _10
    }

    • The Converter contains the following fields:
      • id: String type field. The ID of the Converter. This is a UUID (Universal Unique Identifier) generated by the Agora server to identify a created Converter.
      • createTs: Number type field. The Unix timestamp (s) when the Converter was created.
      • updateTs: Number type field. The Unix timestamp (s) when the Converter configurationwas last updated.
      • state: String type field. The running status of the Converter.
        • connecting: The Converter is connecting to the Agora server.
        • running: The Converter is running properly, and streams are being pushed to the CDN.
        • failed: There is a failure in pushing streams to the CDN.
    • lts: Number type field. The Unix timestamp (ms) when the event occurred on the Agora server.
    • fields: String type field. For the field mask of JSON encoding, please refer to the Google protobuf FieldMask document for details. This is used to specify a subset of theconverter field to be returned. In this example, fields specifies a subset of the id, createTs, updateTs, and state fields in the converter field returned by the Agora server.

    Converter destroyed​

    Notifications notifies your server of this event when a Converter is destroyed, and the streams being pushed to the CDN are stopped.

    For the destruction reason, see the destroyReason field.

    The eventType is 4(ConverterDestroyedEvent). The following is an example payload:


    _11
    {
    _11
    "converter": {
    _11
    "id": "4c014467d647bb87b60b719f6fa57686",
    _11
    "name": "show68_vertical",
    _11
    "createTs": 1603456600,
    _11
    "updateTs": 1603456600
    _11
    },
    _11
    "lts": 1603456600,
    _11
    "destroyReason": "Delete Request",
    _11
    "fields": "id,name,createTs,updateTs"
    _11
    }

    • The Converter contains the following fields:
      • id: String type field. The ID of the Converter. This is a UUID (Universal Unique Identifier) generated by the Agora server to identify a created Converter.
      • name: String type field. The name of the Converter.
      • createTs: Number type field. The Unix timestamp (s) when the Converter was created.
      • updateTs: Number type field. The Unix timestamp (s) when the Converter configurationwas last updated.
    • lts: Number type field. The Unix timestamp (ms) when the event occurred on the Agora server.
    • destroyReason: String type field, which shows the reason for the destruction of the Converter.
      • Delete Request: The Agora server receives your Delete request.
      • Idle Timeout: After the idle state exceeds the set idleTimeOut, all users of the corresponding media streams processed by the Converter leave the channel.
      • Internal Error: Errors related to the Agora server. For example, hardware failure.
    • fields: String type field. For the field mask of JSON encoding, please refer to the Google protobuf FieldMask document for details. This is used to specify a subset of theconverter field to be returned. In this example, fields specifies a subset of the id, createTs, updateTs, and state fields in the converter field returned by the Agora server.

    IP address query API​

    If your server that receives notification callbacks is behind a firewall, call the IP address query API to retrieve the IP addresses of Notifications and configure your firewall to trust all these IP addresses.

    Agora occasionally adjusts the Notifications IP addresses. Best practice is to call this endpoint at least every 24 hours and automatically update the firewall configuration.

    Prototype​

    • Method: GET
    • Endpoint: https://api.agora.io/v2/ncs/ip

    Request header​

    Authorization: You must generate a Base64-encoded credential with the Customer ID and Customer Secret provided by Agora, and then pass the credential to the Authorization field in the HTTP request header.

    Request body​

    This API has no body parameters.

    Response body​

    When the request succeeds, the response body looks like the following:


    _14
    {
    _14
    "data": {
    _14
    "service": {
    _14
    "hosts": [
    _14
    {
    _14
    "primaryIP": "xxx.xxx.xxx.xxx"
    _14
    },
    _14
    {
    _14
    "primaryIP": "xxx.xxx.xxx.xxx"
    _14
    }
    _14
    ]
    _14
    }
    _14
    }
    _14
    }

    Each primary IP field shows an IP address of Notifications server. When you receive a response, you need to note the primary IP fields and add all these IP addresses to your firewall's allowed IP list.

    Considerations​

    • Notifications does not guarantee that notification callbacks arrive at your server in the same order as events occur. Implement a strategy to handle messages arriving out of order.

    • For improved reliability of Notifications, your server may receive more than one notification callback for a single event. Your server must be able to handle repeated messages.

      Tip

      To implement a strategy to ensure that you log only one callback event and ignore duplicate events, use a combination of the noticeId and notifyMs fields in the response body.

    vundefined