Use custom webhook notifications in DMS - Data Management

Configuration

To configure your webhook, go to the Webhook section in your personal settings, enter your endpoint URL, and select the Webhook notification channel.

You must also configure a signature method and a signature key. You can click the Test button to verify the connectivity of your webhook URL. The notification settings panel also allows you to select other channels, such as DingTalk (exclusive), DingTalk, DingTalk chatbot, Email, Lark, and SMS.

For more information, see Configure your personal information and notification methods.

Events

When a notification is triggered in DMS, the system sends an HTTP POST request to the webhook URL that you configured. The request consists of a header and a body.

Request header

DMS-Event: Message Hook

Request body

Parameter	Type	Description
submitterUid	String	The UID of the user who submitted the request.
submitterName	String	The name of the user who submitted the request.
category	String	The feature module, such as ticket, task orchestration, or data warehouse development.
module	String	The business type, such as permission application, data change, schema design, or data export.
event	String	The specific event. Examples: Pending Approval, Succeeded, and Failed.
taskId	String	The ID of the ticket or task flow.
taskName	String	The name of the task.
eventTime	String	The time when the event occurred.
message	String	The system's built-in message text.
targetUsers	Array of objects	The intended recipients. Multiple recipients are supported.
receivers	Array of objects	An array of objects representing the actual recipients. Users without a configured notification method will not receive notifications.
uid	String	The UID of the recipient.
name	String	The name of the recipient.
signatureMethod	String	The signature method. The following signature methods are supported: None (default): No signature is used. HMAC_SHA1: Uses the HMAC-SHA1 algorithm.
signatureText	String	The digital signature, which is an HmacSha1 value calculated from the webhook URL, signature key, and message event. Example: `4mOdwflN1CgxxxxxxxuipuCYYWk=`.

Request body example

{
"messageEvent":{
    "submitterName":"xxx",
    "submitterUid":"167382665015xxxx",
    "category":"ticket",
    "event":"Succeeded",
    "eventTime":1625630049930,
    "message":"[Data Management DMS] Webhook test, code: 144619 ",
    "module":"data change",
    "receivers":[{"name":"xxx1","uid":"167382665015xxxx"},{"name":"xxx2","uid":"167382665016xxxx"}],
    "targetUsers":[{"name":"xxx1","uid":"167382665015xxxx"},{"name":"xxx2","uid":"167382665016xxxx"}],
    "taskName":"Webhook test"
    },
"signatureMethod":"HMAC_SHA1",
"signatureText":"4mOdwflN1Cg5NdM2XPuipuCYYWk="
 }

Response example

{"root":"","success":true}                   //Success
{"root":"error message","success":false}     //Failure

Signature verification

If you configured a signature key, use the following code to verify the signature.

// Verifies the signature of the incoming message
public void callback(String message) {
    JSONObject jsonObject = JSONObject.parseObject(message, Feature.OrderedField);
    String webhookUrl = "Your configured webhook URL";
    String signatureKey = "Your configured signature key";
    String origin = webhookUrl + signatureKey + JSON.toJSONString(jsonObject.getJSONObject("messageEvent"));
    // The signature from the DMS message
    String signatureText = jsonObject.getString("signatureText");
    // The signature calculated on your end
    String expectedSignatureText = signatureByHmacSha1(origin, signatureKey);
    assert Objects.equals(signatureText, expectedSignatureText);
}
public String signatureByHmacSha1(String origin, String key) {
    final String charset = "UTF-8";
    String result = "N/A";
    try {
        SecretKey secretKey = new SecretKeySpec(key.getBytes(charset), "HmacSHA1");
        Mac mac = Mac.getInstance("HmacSHA1");
        mac.init(secretKey);
        result = Base64.getEncoder().encodeToString(mac.doFinal(origin.getBytes(charset)));
    } catch (Exception ex){
    }
    return result;
}

Webhook receiver example

You can create a simple echo script to test your webhook endpoint and view the event payload.

Save the following script as print_http_body.rb.

require 'webrick'
server = WEBrick::HTTPServer.new(:Port => ARGV.first)
server.mount_proc '/' do |req, res|
  puts req.body
end
trap 'INT' do
  server.shutdown
end
server.start

Choose an unused port, such as 8000, and run the script: ruby print_http_body.rb 8000.
In the DMS console, configure the webhook URL, for example, http://my.host:8000/. For more information, see Configure your personal information and notification methods.
If your server requires HTTP Basic Authentication, you can include the username and password in the URL. For example:
```
http://userName:password@my.host:8080/project/test-job
```

In the Modify notification method dialog box, click Test next to your webhook URL. Your server will receive a test notification from DMS.

The server receives a notification similar to the following example:

{
"messageEvent":{
    "submitterName":"xxx",
    "submitterUid":"167382665015xxxx",
    "category":"ticket",
    "event":"Succeeded",
    "eventTime":1625630049930,
    "message":"[Data Management DMS] Webhook test, code: 144619 ",
    "module":"data change",
    "receivers":[{"name":"xxx1","uid":"167382665015xxxx"}],
    "targetUsers":[{"name":"xxx1","uid":"167382665015xxxx"}],
    "taskName":"Webhook test"
    },
"signatureMethod":"HMAC_SHA1",
"signatureText":"4mOdwflN1Cg5NdM2XPuipuCYYWk="
 }
127.0.0.1 - - [20/Apr/2021:20:07:47 CST] "POST / HTTP/1.1" 200 0