Data Management:Send notifications by using a custom webhook URL

Configure a webhook URL as a notification method

Configure notification methods in the DMS console. In the Webhook section, enter a webhook URL in the Webhook URL field and select Webhook.

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

Request for an event notification

When notifications are generated in DMS, DMS sends the notifications to the webhook URL that you specify. This section describes the content of a POST request.

Request header

DMS-Event: Message Hook

Request parameters

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

{"root":"","success":true}                   // The notification is sent.
{"root":"error message","success":false}     // The notification fails to be sent.

Verify the signature and signature key

If you specify a signature and a signature key when configuring the Webhook, you can execute the following code to verify the correctness of the signature and the secret key:

// The callback method used to verify the signature.
public void callback(String message) {
    JSONObject jsonObject = JSONObject.parseObject(str, Feature.OrderedField);
    String webhookUrl = "Webhook URL";
    String password = "Signature key";
    String origin = webhookUrl + password + JSON.toJSONString(jsonObject.getJSONObject("messageEvent"));
    // The signature carried by the DMS message.
    String signatureText = jsonObject.getString("signatureText");
    // The signature calculated on the client 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;
}

Example

You can create an echo script to test a webhook URL and view the notification that is sent by using the webhook URL.

1. Save the following sample code as a script named 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

2. Select a port that is not used, such as port 8000. Run the script: ruby print_http_body.rb 8000.

3. In the DMS console, configure a webhook URL as a notification method, such as http://my.host:8000/. For more information, see Configure personal information and notification methods.

   If a server is configured to use Basic Authentication over the HTTP protocol, you can access the server by using a webhook URL that contains the username and password. Sample webhook URL:

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

4. In the Modify notification method dialog box, click Test on the right of the webhook field. DMS sends a notification to the webhook URL that you specify.

   The following code provides an example on the notification sent by DMS:

   {
   "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