Enable message notification service

The message notification service can inform your server of Agora product events through HTTP/HTTPS protocol requests. This service integrates some events of the Cloud Recording, Media Push and Media Pull products. You can use this service by providing configuration information to Agora.

User configuration

Contact support@agora.io enable the message notification service with the following information:

HTTP/HTTPS server address (URL) to receive notification callbacks.
The product that you want to use the notification service.
Events that you want to be notified, see Cloud Recording Event Type.
Set whether or not to enable the notification Retry option. If you enable this option, the notification server resends the notification callback up to three times after it fails to send the first notification callback in the following situations:
- Your server does not respond in 10 seconds.
- The HTTP status code received from your server is not 200.

After the configuration is completed, the message notification service will take effect after 5 minutes. Therefore, your server needs to respond to the notification server immediately. The response body must be in JSON format.

After configuring the message notification service, we will automatically generate the secret. The secret is a string type key that can be used to generate a signature. You need to save this key for signature verification. See Signature verification for details.

Notification callback format

The notification callback is sent to your server as an HTTP/HTTPS POST request with the body in JSON format. The character encoding is UTF-8.

The header of the notification callback contains the following fields:

Field Name	Value
`Content-Type`	`application/json`
`Agora-Signature`	The signature generated by Agora using the secrect key and the HMAC/SHA1 algorithm. You need to use the secret key and HMAC/SHA1 algorithm to verify the signature value. See Signature verification for details.
`Agora-Signature-V2`	The signature generated by Agora using the secrect key and the HMAC/SHA256 algorithm. You need to use the secret key and HMAC/SHA256 algorithm to verify the signature value. See Signature verification for details.

The body of the notification callback contains the following fields:

Field name	Type	Description
`noticeId`	String	Notification ID, identifying the notification callback when the event occurs.
`productId`	Number	Product ID: `2`: Media Push 3.0 (Client-side SDK API) `3`: Cloud Recording and Extension Service `4`: Media Pull `5`: Media Push (Server-side RESTful API)
`eventType`	Number	The `event type`, see Cloud Recording Event Type, Media Push Event Type and Cloud Player Event Type.
`notifyMs`	Number	The Unix time (ms) when the notification server requests to your server, which is updated each time it resends the notification callback.
`payload`	JSON Object	The content of the events, see Cloud Recording `payload` Field, Media Push `payload` Field and Cloud Player `payload` Field.

Signature verification

We generate the key directly. After using the HMAC/SHA1 and HMAC/SHA256 algorithms, we generate the Agora-Signature and Agora-Signature-V2. You can use the saved key to verify Agora-Signature with the HMAC/SHA1 algorithm or verify Agora-Signature-V2 with the HMAC/SHA256 algorithm. The signature verification sample code is as follows:

Python

HMAC/sha1

#!/usr/bin/env python2
# !-*- coding: utf-8 -*-
import hashlib
import hmac
# Get the raw request body of the notification callback to calculate the signature. request_body in the following code is a binary byte array before deserialization and not a dictionary after deserialization.
request_body = '{"eventMs":1560408533119,"eventType":10,"noticeId":"4eb720f0-8da7-11e9-a43e-53f411c2761f","notifyMs":1560408533119,"payload":{"a":"1","b":2},"productId":1}'
secret = 'secret'
signature = hmac.new(secret, request_body, hashlib.sha1).hexdigest()
print(signature) # 033c62f40f687675f17f0f41f91a40c71c0f134c

HMAC/sha256

#!/usr/bin/env python2
# !-*- coding: utf-8 -*-
import hashlib
import hmac
# Get the raw request body of the notification callback to calculate the signature. request_body in the following code is a binary byte array before deserialization and not a dictionary after deserialization.
request_body = '{"eventMs":1560408533119,"eventType":10,"noticeId":"4eb720f0-8da7-11e9-a43e-53f411c2761f","notifyMs":1560408533119,"payload":{"a":"1","b":2},"productId":1}'
secret = 'secret'
signature2 = hmac.new(secret, request_body, hashlib.sha256).hexdigest()
print(signature2) # 6d3320c60b11101395b7fc8f9068748808a0aa1bfa064438e39d1bc2c7d74d99

Node.js

HMAC/sha1

const crypto = require('crypto')
// Get the raw request body of the notification callback to calculate the signature. requestBody in the following code is a binary byte array before deserialization, not an object after deserialization.
const requestBody = '{"eventMs":1560408533119,"eventType":10,"noticeId":"4eb720f0-8da7-11e9-a43e-53f411c2761f","notifyMs":1560408533119,"payload":{"a":"1","b":2},"productId":1}'
const secret = 'secret'
const signature = crypto.createHmac('sha1', secret).update(requestBody, 'utf8').digest('hex')
console.log(signature) // 033c62f40f687675f17f0f41f91a40c71c0f134c

HMAC/sha256

const crypto = require('crypto')
// Get the raw request body of the notification callback to calculate the signature. requestBody in the following code is a binary byte array before deserialization, not an object after deserialization.
const requestBody = '{"eventMs":1560408533119,"eventType":10,"noticeId":"4eb720f0-8da7-11e9-a43e-53f411c2761f","notifyMs":1560408533119,"payload":{"a":"1","b":2},"productId":1}'
const secret = 'secret'
const signature2 = crypto.createHmac('sha256', secret).update(requestBody, 'utf8').digest('hex')
console.log(signature2) // 6d3320c60b11101395b7fc8f9068748808a0aa1bfa064438e39d1bc2c7d74d99

Java

HMAC/sha1

import javax.crypto.Mac;
import javax.crypto.SecretKey;
import javax.crypto.spec.SecretKeySpec;
public class HmacSha {
    // Convert an encrypted byte array into a hex string.
    public static String bytesToHex(byte[] bytes) {
        StringBuffer sb = new StringBuffer();
        for (int i = 0; i < bytes.length; i++) {
            String hex = Integer.toHexString(bytes[i] & 0xFF);
            if (hex.length() < 2) {
                sb.append(0);
            }
            sb.append(hex);
        }
        return sb.toString();
    }
    // Use the HMAC/SHA1 algorithm and get the encrypted hex string.
    public static String hmacSha1(String message, String secret) {
        try {
            SecretKeySpec signingKey = new SecretKeySpec(secret.getBytes(
                        "utf-8"), "HmacSHA1");
            Mac mac = Mac.getInstance("HmacSHA1");
            mac.init(signingKey);
            byte[] rawHmac = mac.doFinal(message.getBytes("utf-8"));
            return bytesToHex(rawHmac);
        } catch (Exception e) {
            throw new RuntimeException(e);
        }
    }
    public static void main(String[] args) {
        // Get the raw request body of the notification callback to calculate the signature. request_body in the following code is a binary byte array before deserialization and not an object after deserialization.
        String request_body = "{\"eventMs\":1560408533119,\"eventType\":10,\"noticeId\":\"4eb720f0-8da7-11e9-a43e-53f411c2761f\",\"notifyMs\":1560408533119,\"payload\":{\"a\":\"1\",\"b\":2},\"productId\":1}";
        String secret = "secret";
        System.out.println(hmacSha1(request_body, secret)); //033c62f40f687675f17f0f41f91a40c71c0f134c
    }
}

HMAC/sha256

import javax.crypto.Mac;
import javax.crypto.SecretKey;
import javax.crypto.spec.SecretKeySpec;
public class HmacSha {
    // Convert an encrypted byte array into a hex string.
    public static String bytesToHex(byte[] bytes) {
        StringBuffer sb = new StringBuffer();
        for (int i = 0; i < bytes.length; i++) {
            String hex = Integer.toHexString(bytes[i] & 0xFF);
            if (hex.length() < 2) {
                sb.append(0);
            }
            sb.append(hex);
        }
        return sb.toString();
    }
    // Use the HMAC/SHA256 algorithm and get the encrypted hex string.
    public static String hmacSha256(String message, String secret) {
        try {
            SecretKeySpec signingKey = new SecretKeySpec(secret.getBytes(
                        "utf-8"), "HmacSHA256");
            Mac mac = Mac.getInstance("HmacSHA256");
            mac.init(signingKey);
            byte[] rawHmac = mac.doFinal(message.getBytes("utf-8"));
            return bytesToHex(rawHmac);
        } catch (Exception e) {
            throw new RuntimeException(e);
        }
    }
    public static void main(String[] args) {
        // Get the raw request body of the notification callback to calculate the signature. request_body in the following code is a binary byte array before deserialization and not an object after deserialization.
        String request_body = "{\"eventMs\":1560408533119,\"eventType\":10,\"noticeId\":\"4eb720f0-8da7-11e9-a43e-53f411c2761f\",\"notifyMs\":1560408533119,\"payload\":{\"a\":\"1\",\"b\":2},\"productId\":1}";
        String secret = "secret";
        System.out.println(hmacSha256(request_body, secret)); //033c62f40f687675f17f0f41f91a40c71c0f134c
    }
}

Considerations

Your server does not receive messages in the same order as events occur.
For the reliability of the notification callbacks, the notification server may send at least two notification callbacks when the event occurs. Hence, your server should be able to handle duplicate messages.