How to customize webhook notifications in DMS - Data Management

Configure a webhook URL

In the DMS console, open the notification method settings.
In the Webhook section, enter your endpoint in the Webhook URL field.
Select Webhook to enable it as a notification channel.

For details, see Configure personal information and notification methods.

POST request format

When a notification is triggered, DMS sends a POST request to your webhook URL.

Request header

Header	Value	Description
`DMS-Event`	`Message Hook`	Identifies the request as a DMS webhook notification.

Request body

Parameter	Type	Description
`submitterUid`	String	ID of the account that submitted the task.
`submitterName`	String	Name of the account that submitted the task.
`category`	String	Module the task belongs to, such as Tickets, Task Orchestration, or Data Warehouse Development.
`module`	String	Business type, such as permission application, data change, schema design, or data export.
`event`	String	Event triggered by the task status, such as pending approval, success, or failure.
`taskId`	String	ID of the ticket or task flow.
`taskName`	String	Name of the task.
`eventTime`	String	Time when the event occurred.
`message`	String	Preset message from DMS.
`targetUsers`	Array	One or more intended recipients of the notification. Each entry contains `uid` and `name`.
`receivers`	Array	One or more recipients that actually receive the notification. Recipients who have not configured a notification method do not receive the notification. Each entry contains `uid` and `name`.
`signatureMethod`	String	Signature method for the webhook. Valid values: None (default, no signature used), HMAC_SHA1 (Hashed Message Authentication Code Secure Hash Algorithm 1).
`signatureText`	String	Digital signature calculated using HMAC_SHA1, based on the webhook URL, password, and message event. Example: `4mOdwflN1CgxxxxxxxuipuCYYWk=`.

Sample request

{
  "messageEvent": {
    "submitterName": "xxx",
    "submitterUid": "167382665015xxxx",
    "category": "Tickets",
    "event": "Success",
    "eventTime": 1625630049930,
    "message": "[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="
}

Sample responses

Success:

{"root": "", "success": true}

Failure:

{"root": "error message", "success": false}

Verify the signature

If you enable HMAC_SHA1 signing when configuring the webhook, verify incoming requests by recalculating the signature on your server and comparing it against signatureText.

The signature input is the concatenation of: webhookUrl + password + JSON.toJSONString(messageEvent).

// Verify the signature from a DMS webhook request
public void callback(String message) {
    JSONObject jsonObject = JSONObject.parseObject(message, Feature.OrderedField);
    String webhookUrl = "Webhook URL";
    String password = "Signature key";
    String origin = webhookUrl + password + JSON.toJSONString(jsonObject.getJSONObject("messageEvent"));

    // The signature carried in the DMS request
    String signatureText = jsonObject.getString("signatureText");

    // The signature recalculated on the server side
    String expectedSignatureText = signatureByHmacSha1(origin, password);
    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;
}

Troubleshooting signature verification failures

If the signature verification fails even though the payload appears to be from DMS, check the following:

Signature key: Make sure the password used on your server matches the signature key configured in DMS.
Input string order: The input to HMAC_SHA1 must be webhookUrl + password + JSON.toJSONString(messageEvent) — in that exact order.
JSON serialization: The messageEvent object must be serialized to JSON before concatenation. Using the raw request body string instead of re-serializing the parsed object may produce a different result.
Character encoding: Encode all strings as UTF-8. Mismatched encoding between DMS and your server causes signature mismatches.
Proxy or load balancer: If your server sits behind a proxy or load balancer, confirm that it does not modify the request body or headers before your code receives them.

Test your webhook

Use a local echo server to inspect the raw POST request that DMS sends.

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

Start the server on an available port:
```
ruby print_http_body.rb 8000
```
In the DMS console, configure http://my.host:8000/ as the webhook URL. For details, see Configure personal information and notification methods.new DMS console

In the Modify notification method dialog box, click Test on the right of the webhook URL field. DMS sends a test notification to your endpoint. The echo server prints the request body, which looks similar to:

{
  "messageEvent": {
    "submitterName": "xxx",
    "submitterUid": "167382665015xxxx",
    "category": "Tickets",
    "event": "Success",
    "eventTime": 1625630049930,
    "message": "[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

If your server uses HTTP Basic Authentication, include credentials directly in the webhook URL:

http://userName:password@my.host:8080/project/test-job