HTTP Callback Overview

• For an internal app, we recommend subscribing to callback events directly from the Developer Console. For details, see Configure Event Subscription.
• For a third-party enterprise app, we recommend subscribing to callback events through SyncHTTP push or RDS push. Both methods let you use the pushed data directly and are simpler to configure. For details, see Callback Overview.
• The outbound IP addresses for HTTP push are 203.119.0.0/16, 140.205.0.0/16, 106.11.0.0/16, and 198.11.0.0/16.

​

Use Cases

• When your business requires high data timeliness. For example, when an employee joins or leaves, the app must update user data immediately. In this case, subscribe to Contacts events.
• When your app needs to respond promptly to user actions. For example, when a user joins a group chat, the app can subscribe to group chat events and send a welcome message when the user enters the group chat.
• When an Admin activates a third-party enterprise app, DingTalk pushes the enterprise authorized app activation event. Developers can activate the organization and enable the app based on the pushed corpid.

​

HTTP Event Callback Process

1. Configure an HTTP request endpoint on the DingTalk Open Platform to receive pushed callback events.
2. DingTalk pushes callback event data packages to the HTTP endpoint configured for the app. The data is encrypted with the encryption/decryption key entered in the Developer Console when the app was created, and signed with the app Token you provided. For details, see Test the Callback URL Event.
3. After receiving the push, the app must verify the signature, decrypt the data, and return JSON data that contains the encrypted string.
4. Call the Register Event Callback API to receive callback events.

​

Configure the Request Endpoint and Events

1. Sign in to the Developer Console. Find the app you created and open its details page.
2. Click Development Management, then click Edit, and set the push type to HTTP Push.
3. Configure the HTTP endpoint used to receive requests.
   • token: Each time DingTalk pushes event data to your endpoint, it includes a token that is used to generate the signature and verify the legitimacy of the callback request. It must contain only English letters or digits and be 3 to 32 characters long.
   • Data Encryption Key: Click Auto Generate to generate an AES key. This is the parameter used to encrypt and decrypt callback message content, and it is the Base64-encoded AES key. For usage, see Message Encryption and Decryption.
   • Callback URL: The URL used to receive subscription event requests. When a subscribed event is triggered, DingTalk sends a corresponding HTTP POST request to this URL. Note Each app can configure only one callback URL. All event notifications for the app’s subscribed events are sent to this request URL.
4. After completing the configuration, when you click the Validate button, the Open Platform pushes an application/json POST request to the URL you configured to verify its legitimacy. The request is as follows:
   {
       "encrypt":"HJ+q6tp1qhl9L1+++j74xxxx"   // Encrypted string. See the encryption and decryption section below.
   }
   
   When you receive the POST validation request from the Open Platform, decrypt it and return an encrypted string containing success (in JSON format) within 1500 ms. After the DingTalk Open Platform receives the returned JSON, it decrypts it. If it obtains the expected success string, the callback push is verified as normal; otherwise, the callback is judged as failed.
5. After successfully configuring the request endpoint, click Save in the upper-right corner.

​

Receive and Respond to Events

• Receiving Event Information When an event occurs, DingTalk proactively sends a POST request to the configured HTTP endpoint, pushing the corresponding event information. For example, after you subscribe to Contacts events, when the Contacts change, DingTalk pushes the event information to the registered HTTP endpoint in the following format.
  • The request URL format is as follows:
    http://your-registered-HTTP-endpoint?signature=111108bb8e6dbc2xxxx&timestamp=1783610513&nonce=380320111
    
  • The JSON data included is as follows:
    {
        "encrypt":"1ojQf0NSvw2WPvW7LijxS8UvISr8pdDP+rXpPbcLGOmIBNbWetRg7IP0vdhVgkVwSoZBJeQwY2zhROsJq/HJ+q6tp1qhl9L1+ccC9ZjKs1wV5bmA9NoAWQiZ+7MpzQVq+j74rJQljdVyBdI/dGOvsnBSCxCVW0ISWX0vn9lYTuuHSoaxwCGylH9xRhYHL9bRDskBc7bO0FseHQQasdfghjkl"
    }
    
  Where:
  • signature is the message body signature.
  • timestamp is the timestamp.
  • nonce is a random string.
  • encrypt is the encrypted pushed event information.
• Responding to Event Information For all callback events, after you receive an event push, you must return an encrypted string containing success to DingTalk. Only when this data is returned does DingTalk consider the event push successful. The specific data format returned to DingTalk is as follows:
  {
    "msg_signature":"111108bb8e6dbce3c9671d6fdb69d1506xxxx",
    "timeStamp":"1783610513",
    "nonce":"123456",
    "encrypt":"1ojQf0NSvw2WPvW7LijxS8UvISr8pdDP+rXpPbcLGOmIxxxx"
   }
  
  Where:
  • msg_signature is the message body signature.
  • timeStamp is the timestamp.
  • nonce is a random string.
  • encrypt is the encrypted success string.

​

Message Encryption and Decryption

• random is a 16-byte random string.
• msg_len is the 4-byte length of msg, in network byte order.
• msg is the plaintext message body.
• key is the app’s suiteKey.

• Base64-decode the ciphertext: aes_msg=Base64_Decode(encrypt);
• Use AESKey to perform AES decryption: rand_msg=AES_Decrypt(aes_msg);

public Map<String, String> callBack(HttpServletRequest request,
                                    @RequestParam(value = "msg_signature", required = false) String msg_signature,
                                    @RequestParam(value = "timestamp", required = false) String timeStamp,
                                    @RequestParam(value = "nonce", required = false) String nonce,
                                    @RequestBody(required = false) JSONObject json) {
    try {
        // 1. Get the encryption/decryption parameters from the HTTP request

        // 2. Use the encryption/decryption type
        // Notes on Constant.OWNER_KEY:
        // 1. Events subscribed from the Developer Console are app-level event pushes.
        //      In this case, OWNER_KEY is the app's APP_KEY (internal app) or SUITE_KEY (third-party app).
        // 2. Events subscribed by calling the event subscription API are enterprise-level event pushes.
        //      In this case, OWNER_KEY is the organization's CORP_ID (internal app) or SUITE_KEY (third-party app).
        DingCallbackCrypto callbackCrypto = new DingCallbackCrypto(Constant.AES_TOKEN, Constant.AES_KEY, Constant.OWNER_KEY);
        String encryptMsg = json.getString("encrypt");
        String decryptMsg = callbackCrypto.getDecryptMsg(msg_signature, timeStamp, nonce, encryptMsg);

        // 3. Deserialize the callback event JSON data
        JSONObject eventJson = JSON.parseObject(decryptMsg);
        String eventType = eventJson.getString("EventType");

        // 4. Handle by EventType
        if ("check_url".equals(eventType)) {
            // Test the correctness of the callback URL
            bizLogger.info("Test the correctness of the callback URL");
        } else if ("user_add_org".equals(eventType)) {
            // Handle the Contacts user added event
            bizLogger.info("The event occurred: " + eventType);
        } else {
            // Add other registered events
            bizLogger.info("The event occurred: " + eventType);
        }

        // 5. Return the encrypted success data
        Map<String, String> successMap = callbackCrypto.getEncryptedMap("success");
        return successMap;

    } catch (DingTalkEncryptException e) {
        e.printStackTrace();
    }
    return null;
}

{
    "EventType": "user_add_org",
    "TimeStamp": 43535463645,
    "UserId": [
        "user1",
        "user2"
    ],
    "CorpId": "dinge8a56572f80b02a8ffexxxx"
}

​

Related Links

• Event List