Enable Agora Notification Center Service

Last updated 2022/08/25 08:41:54

Agora provides the Notification Center Service (NCS) to inform you of channel events in real time when you use the Real-time Communication (RTC) service.

The following figure illustrates how the Agora NCS works:

Once the Agora NCS is enabled, the Agora service server notifies the Agora NCS server when a subscribed event occurs.
The Agora NCS server informs your server of that event through an HTTPS POST request.
When receiving the request, your server must respond to the Agora NCS server within 10 seconds. The response body must be in JSON format.
When receiving your response with the status code of 200 within 10 seconds after sending the request, the Agora NCS server considers the notification callback is sent successfully. If the Agora NCS server does not receive your response within 10 seconds after sending the request, or if the HTTP status code received from your server is not 200, the notification callback is considered to have failed. The Agora NCS server immediately resends the notification callback after the failure. The interval between these notification attempts gradually increases, until the server stops sending notifications after three retries.

Prerequisites

Before enabling the Agora NCS, ensure that you meet the following requirements:

A valid Agora account. If you do not have an Agora account, see [Sign up for an Agora account](https://docs.agora.io/en/Agora Platform/sign_in_and_sign_up?platform=AllPlatforms).
An active Agora project. If you do not have an Agora project, see [Create a project in Agora Console](https://docs.agora.io/en/Agora Platform/get_appid_token#create-an-agora-project).
Internet access. If your network access is restricted by a firewall, call the IP address query API to get the IP addresses of the Agora NCS server and configure the firewall to allow these IP addresses.

Enable NCS

Follow these steps to enable the NCS on the Agora Console:

Log in to Agora Console, and click the Project Management icon on the left navigation panel.
On the Project Management page, click Config for the project for which you want to enable the NCS.
Under Real-time engagement core, find Notification Center Service, and click Config.
On the Notification Center Service Configuration page, fill in the following information, and click Save:
- Product Name: RTC channel event callbacks.
- Event: Select the channel events that you want to subscribe to.
  
  If the events that you want to subscribe to have high queries per second (QPS), such as events 105 and 106, ensure your server has sufficient processing capacity.
  
  Agora recommends selecting all the events that you want to subscribe to at once to avoid multiple configurations and approval requests.
- Receive Server Location: Select the region where your server that receives the notifications is located. Agora connects to the nearest Agora node server based on your specified location.
- Receive Server URL: The HTTPS address of your server that receives the notifications.
  - To enhance security, the Agora NCS no longer supports HTTP addresses.
  - To reduce the delay in notification delivery, Agora recommends that you 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.
- Secret: The secret used for signature verification. For instructions on how to use the secret for signature verification, see Signature verification.
- Allowed IP List: If your server is behind a firewall, ensure that you have called the [IP address query API](#Get IP addresses of the Agora NCS server) to get the IP addresses of the Agora NCS server and added them to the firewall's allowed IP list, and check the box here.
Agora performs a health test for your configuration, as follows:
1. The NCS 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 needs to respond to the Agora NCS server within 10 seconds with a status code of 200. The response body must be in JSON format.
  
  When the NCS health test succeeds, click Save NCS Configuration.
  
  If the NCS health test fails, follow the prompts 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 NCS 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 NCS 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 NCS 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.
Read the prompt, and click Save NCS Configuration.

After your configuration is approved, the Status of Notification Center Service shows Enabled.

Get IP addresses of the Agora NCS server

If your server that receives notification callbacks is behind a firewall, you need to call the IP address query API to get the IP addresses of the Agora NCS server and configure your firewall to trust all these IP addresses.

Agora occasionally adjusts the IP addresses of the Agora NCS server. Therefore, Agora highly recommends that you call the IP address query API at least every 24 hours and automatically update the firewall configuration; otherwise, your server might not receive the notification callbacks.

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. See HTTP authentication for details.

Request body

This API has no body parameters.

Response body

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

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

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

Considerations

The Agora NCS 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 the Agora NCS, there can be more than one notification callback for each event, and your server needs to be able to handle repeated messages.

Is this page helpful?

Yes