Building a Custom DingTalk Event Distribution Platform with Callback Integration

In previous sessions we demonstrated simple DingTalk approval and address examples; this article shows how to quickly build a custom DingTalk event distribution platform that listens to user actions on DingTalk and triggers corresponding business logic, such as post‑approval processing or synchronizing address changes.

Why build a dedicated platform? The earlier one‑way sync (OA system → DingTalk) only updates DingTalk when the internal system changes. By listening to DingTalk events, we achieve bidirectional synchronization (DingTalk → OA) and can react to approval actions that occur inside DingTalk. DingTalk also restricts each enterprise to a single callback URL, so a dispatcher is needed to register one URL and forward events to multiple internal services.

DingTalk event callbacks are created by registering an HTTP endpoint on the DingTalk Open Platform and subscribing to specific events. When an event occurs, DingTalk pushes a JSON payload to the registered URL; the endpoint must return an encrypted JSON containing the string "success" for DingTalk to consider the push successful.

{
  "msg_signature":"111108bb8e6dbce3c9671d6fdb69d15066227608",
  "timeStamp":"1783610513",
  "nonce":"123456",
  "encrypt":"1ojQf0NSvw2WPvW7LijxS8UvISr8pdDP+rXpPbcLGOmIBNbWetRg7IP0vdhVgkVwSoZBJeQwY2zhROsJq/HJ+q6tp1qhl9L1+ccC9ZjKs1wV5bmA9NoAWQiZ+7MpzQVq+j74rJQljdVyBdI/dGOvsnBSCxCVW0ISWX0vn9lYTuuHSoaxwCGylH9xRhYHL9bRDskBc7bO0FseHQQasdfghjkl"
}

Registering a callback triggers DingTalk to send a test POST request to verify the URL. The server must respond with the encrypted "success" JSON. The registration request URL is:

https://oapi.dingtalk.com/call_back/register_call_back?access_token=ACCESS_TOKEN

The request body structure is:

{
  "call_back_tag": ["user_add_org", "user_modify_org", "user_leave_org"],
  "token": "123456",
  "aes_key": "xxxxxxxxlvdhntotr3x9qhlbytb18zyz5zxxxxxxxxx",
  "url": "http://test001.vaiwan.com/eventreceive"
}

Testing the callback URL – DingTalk posts a test payload to the URL; the endpoint must return the encrypted success JSON, otherwise the URL is considered invalid.

The callback payload includes the following fields:

msg_signature : signature of the message body

timeStamp : timestamp

nonce : random string

encrypt : encrypted value of the string "success" (see DingTalk decryption docs)

Below is a sample C# controller that receives DingTalk events, parses the JSON, extracts useful fields such as EventType , processInstanceId , corpId , title , type , staffId , url , processCode , result , and remark , and returns a simple OK response.

[HttpPost("DingEventReceive")]
public async Task
DingEventReceive([FromBody] string value)
{
    var dic = JsonConvert.DeserializeObject
>(value);
    var eventType = dic["EventType"]?.ToString(); // bpms_instance_change, bpms_task_change
    var processInstanceId = dic["processInstanceId"]?.ToString(); // approval instance id
    var corpId = dic["corpId"]?.ToString(); // enterprise id
    var createTime = dic["createTime"].ToString(); // creation time
    var title = dic["title"].ToString(); // title
    var type = dic["type"].ToString(); // start / finish / terminate
    var staffId = dic["staffId"].ToString(); // initiator
    var url = dic["url"].ToString(); // approval page URL
    var processCode = dic["processCode"].ToString(); // template code
    var result = dic["result"].ToString(); // agree / refuse
    var remark = dic["remark"].ToString(); // comment
    return Ok(1);
}

After receiving callbacks, the dispatcher forwards the relevant events to the appropriate internal systems (e.g., System A, System B) based on business needs; the actual forwarding code is omitted for brevity.

With the platform in place, simple forms can be filled directly in DingTalk and sent via callbacks to internal systems for archiving, while more complex forms remain in the internal system, allowing flexible data collection.

For further details, refer to the official DingTalk documentation and feel free to leave questions or suggestions in the comments.