Skip to main content

You are viewing Agora Docs forBetaproducts and features. Switch to Docs

Receive notifications about channel events

A webhook is a user-defined callback over HTTP. You use webhooks to notify your app or back-end system when certain Voice Calling 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 Voice Calling events you subscribe to:

rtc-channel

  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.

      In test event callbacks, the channelName is test_webhook, and the uid is 12121212.

    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.

Handle redundant notifications and abnormal user activity

When using Notifications to maintain the online status of your app users, your server might experience the following issues:

  • Message notifications are redundant. You receive multiple notifications because the Agora Notifications server can send more than one notification callback for each channel event to ensure reliability of the service.

  • Message notifications arrive out of order. Network issues cause callbacks to arrive at your server in a different order than the order of event occurrence.

To accurately maintain the online status of users, your server needs to be able to deal with redundant notifications and handle received notifications in the same order as events occur. The following section shows you how to use channel event callbacks to accomplish this.

Handle redundant or out of order notifications

Agora Notifications sends RTC channel event callbacks to your server. All channel events, except for 101 and 102 events, contain the clientSeq field (Unit64) in payload, which represents the sequence number of an event. This field is used to identify the order in which events occur on the app client. For notification callbacks reporting the activities of the same user, the value of the clientSeq field increases as events happen.

Refer to the following steps to use the clientSeq field to enable your server to handle redundant messages, and messages arriving out of order:

  1. Enable Agora Notifications, and subscribe to RTC channel event callbacks. Best practice is to subscribe to the following event types according to your scenario:

    • In the LIVE_BROADCASTING profile: 103, 104, 105, 106, 111, and 112.
    • In the COMMUNICATION profile: 103, 104, 111, and 112.
  2. Use the channel event callbacks to get the latest status updates about the following at your server:

    • Channel lists
    • User lists in each channel
    • Data for each user, including the user ID, user role, whether the user is in a channel, and clientSeq of channel events
  3. When receiving notification callbacks of a user, search for the user in the user lists. If there is no data for the user, create data specific to the user.

  4. Compare the value in the clientSeq field of the latest notification callback you receive with that of the last notification callback handled by your server:

    • If the former is greater than the latter, the notification callback needs to be handled.
    • If the former is less than the latter, the notification callback should be ignored.
  5. When receiving notification callbacks reporting a user leaving a channel, wait for one minute before deleting the user data. If it is deleted immediately, your server cannot handle notifications in the same order as channel events happen when receiving redundant notifications or notifications out of order.

Deal with abnormal user activities

When your server receives a notification callback of event 104 with reason as 999, it means that the user is considered to have abnormal activities due to frequent login and logout actions. In this case, best practice is that your server calls the Banning user privileges API to remove the user from the current channel one minute after receiving such notification callback; otherwise, the notification callbacks your server receives about the user's events might be redundant or arrive out of order, which makes it hard for you to accurately maintain the online status of this user.

Implement online user status tracking

This section provides sample Go code to show how to use channel event callbacks to maintain online user status at your app server.

To maintain a user registry, take the following steps:

  1. Replace the content of the main.go file with the following code:


    _216
    package main
    _216
    _216
    import (
    _216
    "crypto/hmac"
    _216
    "crypto/sha1"
    _216
    "encoding/hex"
    _216
    "encoding/json"
    _216
    "fmt"
    _216
    "io"
    _216
    "log"
    _216
    "net/http"
    _216
    "sync"
    _216
    "time"
    _216
    )
    _216
    _216
    const secret = "<Add Your secret key here>"
    _216
    _216
    type WebhookRequest struct {
    _216
    NoticeID string `json:"noticeId"`
    _216
    ProductID int64 `json:"productId"`
    _216
    EventType int `json:"eventType"`
    _216
    Payload Payload `json:"payload"`
    _216
    }
    _216
    _216
    type Payload struct {
    _216
    ClientSeq int64 `json:"clientSeq"`
    _216
    UID int `json:"uid"`
    _216
    ChannelName string `json:"channelName"`
    _216
    }
    _216
    _216
    const (
    _216
    EventBroadcasterJoin = 103
    _216
    EventBroadcasterQuit = 104
    _216
    EventAudienceJoin = 105
    _216
    EventAudienceQuit = 106
    _216
    EventChangeRoleToBroadcaster = 111
    _216
    EventChangeRoleToAudience = 112
    _216
    _216
    RoleBroadcaster = 1
    _216
    RoleAudience = 2
    _216
    WaitTimeoutMs = 60 * 1000
    _216
    )
    _216
    _216
    var (
    _216
    channels = make(map[string]*Channel)
    _216
    mu sync.Mutex
    _216
    )
    _216
    _216
    type User struct {
    _216
    UID int
    _216
    Role int
    _216
    IsOnline bool
    _216
    LastClientSeq int64
    _216
    }
    _216
    _216
    type Channel struct {
    _216
    Users map[int]*User
    _216
    }
    _216
    _216
    func handleNCSEvent(channelName string, uid int, eventType int, clientSeq int64) {
    _216
    mu.Lock()
    _216
    defer mu.Unlock()
    _216
    _216
    if !isValidEventType(eventType) {
    _216
    return
    _216
    }
    _216
    _216
    isOnlineInNotice := isUserOnlineInNotice(eventType)
    _216
    roleInNotice := getUserRoleInNotice(eventType)
    _216
    _216
    channel, exists := channels[channelName]
    _216
    if !exists {
    _216
    channel = &Channel{Users: make(map[int]*User)}
    _216
    channels[channelName] = channel
    _216
    fmt.Println("New channel", channelName, "created")
    _216
    }
    _216
    _216
    user, exists := channel.Users[uid]
    _216
    if !exists {
    _216
    user = &User{UID: uid, Role: roleInNotice, IsOnline: isOnlineInNotice, LastClientSeq: clientSeq}
    _216
    channel.Users[uid] = user
    _216
    _216
    if isOnlineInNotice {
    _216
    fmt.Println("New User", uid, "joined channel", channelName)
    _216
    } else {
    _216
    delayedRemoveUserFromChannel(channelName, uid, clientSeq)
    _216
    }
    _216
    } else if clientSeq > user.LastClientSeq {
    _216
    user.Role = roleInNotice
    _216
    user.IsOnline = isOnlineInNotice
    _216
    user.LastClientSeq = clientSeq
    _216
    _216
    if !isOnlineInNotice && user.IsOnline {
    _216
    fmt.Println("User", uid, "quit channel", channelName)
    _216
    delayedRemoveUserFromChannel(channelName, uid, clientSeq)
    _216
    }
    _216
    }
    _216
    }
    _216
    _216
    func delayedRemoveUserFromChannel(channelName string, uid int, clientSeq int64) {
    _216
    time.AfterFunc(WaitTimeoutMs*time.Millisecond, func() {
    _216
    mu.Lock()
    _216
    defer mu.Unlock()
    _216
    _216
    channel, exists := channels[channelName]
    _216
    if !exists {
    _216
    return
    _216
    }
    _216
    _216
    user, exists := channel.Users[uid]
    _216
    if !exists {
    _216
    return
    _216
    }
    _216
    _216
    if user.LastClientSeq != clientSeq {
    _216
    return
    _216
    }
    _216
    _216
    if !user.IsOnline {
    _216
    delete(channel.Users, uid)
    _216
    fmt.Println("Removed user", uid, "from channel", channelName)
    _216
    } else {
    _216
    fmt.Println("User", uid, "is online while delayed removing, cancelled")
    _216
    }
    _216
    _216
    if len(channel.Users) == 0 {
    _216
    delete(channels, channelName)
    _216
    fmt.Println("Removed channel", channelName)
    _216
    }
    _216
    })
    _216
    }
    _216
    _216
    func isValidEventType(eventType int) bool {
    _216
    return eventType == EventBroadcasterJoin ||
    _216
    eventType == EventBroadcasterQuit ||
    _216
    eventType == EventAudienceJoin ||
    _216
    eventType == EventAudienceQuit ||
    _216
    eventType == EventChangeRoleToBroadcaster ||
    _216
    eventType == EventChangeRoleToAudience
    _216
    }
    _216
    _216
    func isUserOnlineInNotice(eventType int) bool {
    _216
    return eventType == EventBroadcasterJoin ||
    _216
    eventType == EventAudienceJoin ||
    _216
    eventType == EventChangeRoleToBroadcaster ||
    _216
    eventType == EventChangeRoleToAudience
    _216
    }
    _216
    _216
    func getUserRoleInNotice(eventType int) int {
    _216
    if eventType == EventBroadcasterJoin ||
    _216
    eventType == EventBroadcasterQuit ||
    _216
    eventType == EventChangeRoleToBroadcaster {
    _216
    return RoleBroadcaster
    _216
    }
    _216
    return RoleAudience
    _216
    }
    _216
    _216
    func calcSignature(secret, payload string) string {
    _216
    mac := hmac.New(sha1.New, []byte(secret))
    _216
    mac.Write([]byte(payload))
    _216
    return hex.EncodeToString(mac.Sum(nil))
    _216
    }
    _216
    _216
    func verifySignature(requestBody, signature string) bool {
    _216
    calculatedSignature := calcSignature(secret, requestBody)
    _216
    fmt.Println("Calculated Signature:", calculatedSignature)
    _216
    fmt.Println("Received Signature:", signature)
    _216
    return calculatedSignature == signature
    _216
    }
    _216
    _216
    func rootHandler(w http.ResponseWriter, r *http.Request) {
    _216
    response := `<h1>Agora Notifications demo</h1><h2>Port: 80</h2>`
    _216
    w.WriteHeader(http.StatusOK)
    _216
    w.Write([]byte(response))
    _216
    }
    _216
    _216
    func ncsHandler(w http.ResponseWriter, r *http.Request) {
    _216
    agoraSignature := r.Header.Get("Agora-Signature")
    _216
    fmt.Println("Agora-Signature:", agoraSignature)
    _216
    _216
    body, err := ioutil.ReadAll(r.Body)
    _216
    if err != nil {
    _216
    http.Error(w, "Unable to read request body", http.StatusBadRequest)
    _216
    return
    _216
    }
    _216
    _216
    if !verifySignature(string(body), agoraSignature) {
    _216
    http.Error(w, "Invalid signature", http.StatusUnauthorized)
    _216
    return
    _216
    }
    _216
    _216
    var req WebhookRequest
    _216
    if err := json.Unmarshal(body, &req); err != nil {
    _216
    http.Error(w, "Invalid JSON", http.StatusBadRequest)
    _216
    return
    _216
    }
    _216
    _216
    fmt.Printf("Event code: %d Uid: %d Channel: %s ClientSeq: %d\n",
    _216
    req.EventType, req.Payload.UID, req.Payload.ChannelName, req.Payload.ClientSeq)
    _216
    _216
    handleNCSEvent(req.Payload.ChannelName, req.Payload.UID, req.EventType, req.Payload.ClientSeq)
    _216
    _216
    w.WriteHeader(http.StatusOK)
    _216
    w.Write([]byte("Ok"))
    _216
    }
    _216
    _216
    func main() {
    _216
    http.HandleFunc("/", rootHandler)
    _216
    http.HandleFunc("/ncsNotify", ncsHandler)
    _216
    _216
    port := ":80"
    _216
    fmt.Printf("Notifications webhook server started on port %s\n", port)
    _216
    if err := http.ListenAndServe(port, nil); err != nil {
    _216
    log.Fatalf("Failed to start server: %v", err)
    _216
    }
    _216
    }

  2. To test signature verification, follow the steps given in the Enable notifications section.

When adopting the solutions recommended by Agora to maintain user online status, you need to recognize the following:

  • The solutions only guarantee eventual consistency of user status.

  • To improve accuracy, notification callbacks specific to one channel must be handled in a single process.

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

The Agora Notifications server notifies your server of the following RTC channel event types when you use the RTC service:

eventTypeEvent nameDescription
101channel createInitializes the channel.
102channel destroyDestroys the channel.
103broadcaster join channelIn the streaming profile, the host joins the channel.
104broadcaster leave channelIn the streaming profile, the host leaves the channel.
105audience join channelIn the streaming profile, an audience member joins the channel.
106audience leave channelIn the streaming profile, an audience member leaves the channel.
107user join channel with communication modeIn the communication profile, a user joins the channel.
108user leave channel with communication modeIn the communication profile, a user leaves the channel.
111client role change to broadcasterIn the communication profile in RTC v4. x products or in the streaming profile, an audience member switches their user role to host.
112client role change to audienceIn the communication profile in RTC v4. x products or in the streaming profile, a host switches their user role to audience member.

101 channel create

This event type indicates that a channel is initialized (when the first user joins the channel). The payload contains the following fields:

Field nameTypeDescription
channelNameStringThe name of the channel.
tsNumberThe Unix timestamp (s) when the event occurs on the Agora RTC server.
Example

_4
{
_4
"channelName":"test_webhook",
_4
"ts":1560399999
_4
}

102 channel destroy

This event type indicates that the last user in the channel leaves the channel and the channel is destroyed. The payload contains the following fields:

Field nameTypeDescription
channelNameStringThe name of the channel.
tsNumberThe Unix timestamp (s) when the event occurs on the Agora RTC server.
Example

_4
{
_4
"channelName":"test_webhook",
_4
"ts":1560399999
_4
}

103 broadcaster join channel

This event type indicates that a host joins the channel in the streaming profile. The payload contains the following fields:

Field nameTypeDescription
channelNameStringThe name of the channel.
uidNumberThe user ID of the host in the channel.
platformNumberThe platform type of the host's device:
  • 1: Android
  • 2: iOS
  • 5: Windows
  • 6: Linux
  • 7: Web
  • 8: macOS
  • 0: Other platform
clientTypeNumberThe type of services used by the host on Linux. Common return values include:
  • 3: On-premise Recording
  • 10: Cloud Recording
This field is only returned when platform is 6.
clientSeqNumberThe sequence number, which is used to identify the order in which events occur on the app client. You can use the value of this field to sort the events of a user into chronological order.
tsNumberThe Unix timestamp (s) when the event occurs on the Agora RTC server.
Example

_7
{
_7
"channelName":"test_webhook",
_7
"uid":12121212,
_7
"platform":1,
_7
"clientSeq":1625051030746,
_7
"ts":1560396843
_7
}

104 broadcaster leave channel

This event type indicates that a host leaves the channel in the streaming profile. The payload contains the following fields:

Field nameTypeDescription
channelNameStringThe name of the channel.
uidNumberThe user ID of the host in the channel.
platformNumberThe platform type of the host's device:
  • 1: Android
  • 2: iOS
  • 5: Windows
  • 6: Linux
  • 7: Web
  • 8: macOS
  • 0: Other platform
clientTypeNumberThe type of services used by the host on Linux. Common return values include:
  • 3: On-premise Recording
  • 10: Cloud Recording
This field is only returned when platform is 6.
clientSeqNumberThe sequence number, which is used to identify the order in which events occur on the app client. You can use the value of this field to sort the events of a user into chronological order.
reasonNumberThe reason why the host leaves the channel:
  • 1: The host quits the call.
  • 2: The connection between the app client and the Agora RTC server times out, which occurs when the Agora SD-RTN does not receive any data packets from the app client for more than 10 seconds.
  • 3: Permission issues. For example, the host is kicked out of the channel by the administrator through the Banning user privileges RESTful API.
  • 4: Internal issues with the Agora RTC server. For example, the Agora RTC server disconnects from the app client for a short period of time for load balancing. When the load balancing is finished, the Agora RTC server reconnects with the client.
  • 5: The host uses a new device to join the channel, which forces the old device to leave the channel.
  • 9: The app client has multiple IP addresses, therefore the SDK actively disconnects from the Agora RTC server and reconnects. The user is not aware of this process. Check whether the app client has multiple public IP addresses or uses a VPN
  • 10: Due to network connection issues, for example, the SDK does not receive any data packets from the Agora RTC server for more than 4 seconds or the socket connection error occurs, the SDK actively disconnects from the Agora server and reconnects. The user is not aware of this process. Check the network connection status.
  • 999: The user has unusual activities, such as frequent login and logout actions. 60 seconds after receiving the 104 or 106 event callback with reason as 999, your app server needs to call the Banning user privileges API to remove the user from the current channel; otherwise, your server could fail to receive any notification callbacks about the user's events if the user rejoins the channel.
  • 0: Other reasons.
tsNumberThe Unix timestamp (s) when the event occurs on the Agora RTC server.
durationNumberThe length of time (s) that the host stays in the channel.
Example

_9
{
_9
"channelName":"test_webhook",
_9
"uid":12121212,
_9
"platform":1,
_9
"clientSeq":1625051030789,
_9
"reason":1,
_9
"ts":1560396943,
_9
"duration":600
_9
}

105 audience join channel

This event type indicates that an audience member joins the channel in the streaming profile The payload includes the following fields:

Field nameTypeDescription
channelNameStringThe name of the channel.
uidNumberThe user ID of the audience member in the channel.
platformNumberThe platform type of the audience member's device:
  • 1: Android
  • 2: iOS
  • 5: Windows
  • 6: Linux
  • 7: Web
  • 8: macOS
  • 0: Other platform
clientTypeNumberThe type of services used by the host on Linux. Common return values include:
  • 3: On-premise Recording
  • 10: Cloud Recording
This field is only returned when platform is 6.
clientSeqNumberThe sequence number, which is used to identify the order in which events occur on the app client. You can use the value of this field to sort the events of a user into chronological order.
tsNumberThe Unix timestamp (s) when the event occurs on the Agora RTC server.
Example

_7
{
_7
"channelName":"test_webhook",
_7
"uid":12121212,
_7
"platform":1,
_7
"clientSeq":1625051035346,
_7
"ts":1560396843
_7
}

106 audience leave channel

This event type indicates that an audience member leaves the channel in the streaming profile. The payload includes the following fields:

Field nameTypeDescription
channelNameStringThe name of the channel.
uidNumberThe user ID of the audience member in the channel.
platformNumberThe platform type of the audience member's device:
  • 1: Android
  • 2: iOS
  • 5: Windows
  • 6: Linux
  • 7: Web
  • 8: macOS
  • 0: Other platform
clientTypeNumberThe type of services used by the audience member on Linux. Common return values include:
  • 3: On-premise Recording
  • 10: Cloud Recording
This field is only returned when platform is 6.
clientSeqNumberThe sequence number, which is used to identify the order in which events occur on the app client. You can use the value of this field to sort the events of a user into chronological order.
reasonNumberThe reason why the audience member leaves the channel:
  • 1: The audience member quits the call.
  • 2: The connection between the app client and the Agora RTC server times out, which occurs when the Agora SD-RTN does not receive any data packets from the app client for more than 10 seconds.
  • 3: Permission issues. For example, the audience member is kicked out of the channel by the administrator through the Banning user privileges RESTful API.
  • 4: Internal issues with the Agora RTC server. For example, the Agora RTC server disconnects from the app client for a short period of time for load balancing. When the load balancing is finished, the Agora RTC server reconnects with the client.
  • 5: The audience member uses a new device to join the channel, which forces the old device to leave the channel.
  • 9: The app client has multiple IP addresses, therefore the SDK actively disconnects from the Agora RTC server and reconnects. The user is not aware of this process. Check whether the app client has multiple public IP addresses or uses a VPN
  • 10: Due to network connection issues, for example, the SDK does not receive any data packets from the Agora RTC server for more than 4 seconds or the socket connection error occurs, the SDK actively disconnects from the Agora server and reconnects. The user is not aware of this process. Check the network connection status.
  • 999: The user has unusual activities, such as frequent login and logout actions. 60 seconds after receiving the 104 or 106 event callback with reason as 999, your app server needs to call the Banning user privileges API to remove the user from the current channel; otherwise, your server could fail to receive any notification callbacks about the user's events if the user rejoins the channel.
  • 0: Other reasons.
tsNumberThe Unix timestamp (s) when the event occurs on the Agora RTC server.
durationNumberThe length of time (s) that the audience member stays in the channel.
Example

_9
{
_9
"channelName":"test_webhook",
_9
"uid":12121212,
_9
"platform":1,
_9
"clientSeq":1625051035390,
_9
"reason":1,
_9
"ts":1560396943,
_9
"duration":600
_9
}

107 user join channel with communication mode

This event type indicates that a user joins the channel in the communication profile. The payload includes the following fields:

Field nameTypeDescription
channelNameStringThe name of the channel.
uidNumberThe user ID of the user in the channel.
platformNumberThe platform type of the host's device:
  • 1: Android
  • 2: iOS
  • 5: Windows
  • 6: Linux
  • 7: Web
  • 8: macOS
  • 0: Other platform
clientSeqNumberThe sequence number, which is used to identify the order in which events occur on the app client. You can use the value of this field to sort the events of a user into chronological order.
tsNumberThe Unix timestamp (s) when the event occurs on the Agora RTC server.
Example

_7
{
_7
"channelName":"test_webhook",
_7
"uid":12121212,
_7
"platform":1,
_7
"clientSeq":1625051035369,
_7
"ts":1560396834
_7
}

108 user leave channel with communication mode

This event type indicates that a user leaves the channel in the communication profile. The payload includes the following fields:

Field nameTypeDescription
channelNameStringThe name of the channel.
uidNumberThe user ID of the user in the channel.
platformNumberThe platform type of the user's device:
  • 1: Android
  • 2: iOS
  • 5: Windows
  • 6: Linux
  • 7: Web
  • 8: macOS
  • 0: Other platform
clientSeqNumberThe sequence number, which is used to identify the order in which events occur on the app client. You can use the value of this field to sort the events of a user into chronological order.
reasonNumberThe reason why a user leaves the channel:
  • 1: The user quits the call.
  • 2: The connection between the app client and the Agora RTC server times out, which occurs when the Agora SD-RTN does not receive any data packets from the app client for more than 10 seconds.
  • 3: Permission issues. For example, the user is kicked out of the channel by the administrator through the Banning user privileges RESTful API.
  • 4: Internal issues with the Agora RTC server. For example, the Agora RTC server disconnects from the app client for a short period of time for load balancing. When the load balancing is finished, the Agora RTC server reconnects with the client.
  • 5: The user uses a new device to join the channel, which forces the old device to leave the channel.
  • 9: The app client has multiple IP addresses, therefore the SDK actively disconnects from the Agora RTC server and reconnects. The user is not aware of this process. Check whether the app client has multiple public IP addresses or uses a VPN
  • 10: Due to network connection issues, for example, the SDK does not receive any data packets from the Agora RTC server for more than 4 seconds or the socket connection error occurs, the SDK actively disconnects from the Agora server and reconnects. The user is not aware of this process. Check the network connection status.
  • 999: The user has unusual activities, such as frequent login and logout actions. 60 seconds after receiving the 104 or 106 event callback with reason as 999, your app server needs to call the Banning user privileges API to remove the user from the current channel; otherwise, your server could fail to receive any notification callbacks about the user's events if the user rejoins the channel.
  • 0: Other reasons.
tsNumberThe Unix timestamp (s) when the event occurs on the Agora RTC server.
durationNumberThe length of time (s) that the user stays in the channel.
Example

_9
{
_9
"channelName":"test_webhook",
_9
"uid":12121212,
_9
"platform":1,
_9
"clientSeq":1625051037369,
_9
"reason":1,
_9
"ts":1560496834,
_9
"duration":600
_9
}

111 client role change to broadcaster

This event type indicates that an audience member calls setClientRole to switch their user role to host in the streaming profile. The payload includes the following fields:

Field nameTypeDescription
channelNameStringThe name of the channel.
uidNumberThe user ID of the user in the channel.
clientSeqNumberThe sequence number, which is used to identify the order in which events occur on the app client. You can use the value of this field to sort the events of a user into chronological order.
tsNumberThe Unix timestamp (s) when the event occurs on the Agora RTC server.
Example

_6
{
_6
"channelName":"test_webhook",
_6
"uid":12121212,
_6
"clientSeq":1625051035469,
_6
"ts":1560396834
_6
}

112 client role change to audience

This event type indicates that a host call setClientRole to switch their user role to audience member in the streaming profile. The payload contains the following fields:

Field nameTypeDescription
channelNameStringThe name of the channel.
uidNumberThe user ID of the user in the channel.
clientSeqNumberThe sequence number, which is used to identify the order in which events occur on the app client. You can use the value of this field to sort the events of a user into chronological order.
tsNumberThe Unix timestamp (s) when the event occurs on the Agora RTC server.
Example

_6
{
_6
"channelName":"test_webhook",
_6
"uid":12121212,
_6
"clientSeq":16250510358369,
_6
"ts":1560496834
_6
}

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.

Voice Calling