Skip to main content

You are viewing Agora Docs forBeta products 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 tell Notifications the URL of the webhooks you have configured to receive these events. Notifications sends notifications of your events to your webhooks 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:

  1. A user commits an action that creates an event. For example, creates a channel.
  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 a Java project for your server

    Your server receives and handles notifications. The RootHandler handles requests sent to the root address of your server and the NcsHandler handles the notifications sent to <your server address>/ncsNotify. To set up your server, create a new Java project and add the following code to a file named Main.java:


    _34
    import java.io.IOException;
    _34
    import java.net.InetSocketAddress;
    _34
    import com.sun.net.httpserver.HttpServer;
    _34
    _34
    public class Main {
    _34
    public static int port = 80;
    _34
    _34
    public static void main(String[] args) {
    _34
    // Start http server
    _34
    SimpleHttpServer httpServer = new SimpleHttpServer();
    _34
    httpServer.Start(port);
    _34
    }
    _34
    _34
    static class SimpleHttpServer {
    _34
    private HttpServer server;
    _34
    _34
    public void Start(int port) {
    _34
    try {
    _34
    server = HttpServer.create(new InetSocketAddress(port), 0);
    _34
    System.out.println("Notifications webhook server started on port " + port);
    _34
    server.createContext("/", new Handlers.RootHandler());
    _34
    server.createContext("/ncsNotify", new Handlers.NcsHandler());
    _34
    server.setExecutor(null);
    _34
    server.start();
    _34
    } catch (IOException e) {
    _34
    e.printStackTrace();
    _34
    }
    _34
    }
    _34
    _34
    public void Stop() {
    _34
    server.stop(0);
    _34
    }
    _34
    }
    _34
    }

  2. Add a JSON library to your project

    The body of an HTTP request that your server receives contains event parameters in JSON format. To read these parameters download the json-simple-1.1.1.jar library and add it to your JAVA project.

  3. Handle Notifications callbacks

    To define the RootHandler and the NcsHandler, create a new file named Handlers.java in your Java project folder. Add the following code to this file:

  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 <local server port>

      You see a Forwarding URL displayed such as https://1111-123-456-789-99.ap.ngrok.io. This is the public URL for your local server that you use to enable Notifications.

Enable Notifications

To enable Notifications:

  1. Log in to Agora Console. On the Project Management 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.

      • To enhance 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 the 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 HMAC/SHA1 algorithm.
    • To verify Agora-Signature-V2, use the secret, the raw request body, and the HMAC/SHA2 algorithm.

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

  1. In your JAVA project folder, add a new file named Signature.java containing the following code:


    _40
    import javax.crypto.Mac;
    _40
    import javax.crypto.spec.SecretKeySpec;
    _40
    _40
    public class Signature {
    _40
    static String secret = "<your NCS secret>";
    _40
    _40
    public static String bytesToHex(byte[] bytes) {
    _40
    // Convert an encrypted byte array into a hex string
    _40
    StringBuffer sb = new StringBuffer();
    _40
    for (int i = 0; i < bytes.length; i++) {
    _40
    String hex = Integer.toHexString(bytes[i] & 0xFF);
    _40
    if (hex.length() < 2) {
    _40
    sb.append(0);
    _40
    }
    _40
    sb.append(hex);
    _40
    }
    _40
    return sb.toString();
    _40
    }
    _40
    _40
    // Use the HMAC/SHA1 algorithm and get the encrypted hex string
    _40
    // To use the HMAC/SHA256 algorithm, replace "HmacSHA1" with "HmacSHA256"
    _40
    public static String hmacSha1(String message) {
    _40
    try {
    _40
    SecretKeySpec signingKey = new SecretKeySpec(secret.getBytes(
    _40
    "utf-8"), "HmacSHA1");
    _40
    Mac mac = Mac.getInstance("HmacSHA1");
    _40
    mac.init(signingKey);
    _40
    byte[] rawHmac = mac.doFinal(message.getBytes("utf-8"));
    _40
    return bytesToHex(rawHmac);
    _40
    } catch (Exception e) {
    _40
    throw new RuntimeException(e);
    _40
    }
    _40
    }
    _40
    _40
    public static boolean verify(String request_body, String signature) {
    _40
    // Check the signature against the encrypted request body
    _40
    // Returns true if the signature matches the encrypted hex string
    _40
    return (hmacSha1(request_body).equals(signature));
    _40
    }
    _40
    }

    Make sure you update your Notifications secret in the code. To verify authenticity using Agora-Signature-V2, replace HmacSHA1 with HmacSHA256 in the sample code.

  2. To verify data in the Notifications callback, add the following code to NcsHandler:


    _3
    // Pass the request body and the signature from the request header
    _3
    boolean isVerified = Signature.verify(body, agoraSignature);
    _3
    System.out.println("Signature verified: " + isVerified);

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

IP address query API

If your server that receives notification callbacks is behind a firewall, you need to 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.
  • Your server needs to be able to handle messages arriving out of order.
  • To improve the reliability of Notifications, there can be more than one notification callback for each event, and your server needs to be able to handle repeated messages.

Voice Calling