Cara menyesuaikan notifikasi webhook di DMS - Data Management

Data Management (DMS) mendukung URL webhook kustom sebagai saluran notifikasi, selain pesan teks, email, notifikasi DingTalk, dan pesan chatbot DingTalk. Ketika suatu event terjadi di DMS, DMS mengirim permintaan POST ke URL webhook yang Anda konfigurasikan.

Konfigurasi URL webhook

Di Konsol DMS, buka pengaturan metode notifikasi.
Pada bagian Webhook, masukkan titik akhir Anda di bidang Webhook URL.
Pilih Webhook untuk mengaktifkannya sebagai saluran notifikasi.

Untuk detailnya, lihat Konfigurasi informasi pribadi dan metode notifikasi.

Format permintaan POST

Ketika notifikasi dipicu, DMS mengirim permintaan POST ke URL webhook Anda.

Header permintaan

Header	Nilai	Deskripsi
`DMS-Event`	`Message Hook`	Mengidentifikasi permintaan sebagai notifikasi webhook DMS.

Badan permintaan

Parameter	Tipe	Deskripsi
`submitterUid`	String	ID akun yang mengirimkan task.
`submitterName`	String	Nama akun yang mengirimkan task.
`category`	String	Modul tempat task tersebut berada, seperti Tiket, Orkestrasi Task, atau Pengembangan Data Warehouse.
`module`	String	Jenis bisnis, seperti permohonan izin, perubahan data, desain skema, atau ekspor data.
`event`	String	Event yang dipicu oleh status task, seperti menunggu persetujuan, sukses, atau gagal.
`taskId`	String	ID tiket atau alur task.
`taskName`	String	Nama task.
`eventTime`	String	Waktu saat event terjadi.
`message`	String	Pesan prasetel dari DMS.
`targetUsers`	Array	Satu atau beberapa penerima yang dituju oleh notifikasi. Setiap entri berisi `uid` dan `name`.
`receivers`	Array	Satu atau beberapa penerima yang benar-benar menerima notifikasi. Penerima yang belum mengonfigurasi metode notifikasi tidak akan menerima notifikasi tersebut. Setiap entri berisi `uid` dan `name`.
`signatureMethod`	String	Metode signature untuk webhook. Nilai yang valid: None (default, tanpa signature), HMAC_SHA1 (Hashed Message Authentication Code Secure Hash Algorithm 1).
`signatureText`	String	Signature digital yang dihitung menggunakan HMAC_SHA1, berdasarkan URL webhook, password, dan event pesan. Contoh: `4mOdwflN1CgxxxxxxxuipuCYYWk=`.

Contoh permintaan

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

Contoh tanggapan

Sukses:

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

Gagal:

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

Verifikasi signature

Jika Anda mengaktifkan penandatanganan HMAC_SHA1 saat mengonfigurasi webhook, verifikasi permintaan masuk dengan menghitung ulang signature di server Anda dan membandingkannya dengan signatureText.

Input signature adalah gabungan dari: webhookUrl + password + JSON.toJSONString(messageEvent).

// Verifikasi signature dari permintaan webhook DMS
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"));

    // Signature yang dibawa dalam permintaan DMS
    String signatureText = jsonObject.getString("signatureText");

    // Signature yang dihitung ulang di sisi server
    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;
}

Pemecahan masalah kegagalan verifikasi signature

Jika verifikasi signature gagal meskipun muatan tampak berasal dari DMS, periksa hal berikut:

Kunci signature: Pastikan password yang digunakan di server Anda sesuai dengan kunci tanda tangan yang dikonfigurasi di DMS.
Urutan string input: Input untuk HMAC_SHA1 harus berupa webhookUrl + password + JSON.toJSONString(messageEvent) — dalam urutan yang tepat tersebut.
Serialisasi JSON: Objek messageEvent harus diserialisasi ke JSON sebelum digabungkan. Menggunakan string badan permintaan mentah alih-alih menyerialisasi ulang objek yang telah diurai dapat menghasilkan nilai yang berbeda.
Encoding karakter: Encode semua string sebagai UTF-8. Perbedaan encoding antara DMS dan server Anda menyebabkan ketidakcocokan signature.
Proxy atau load balancer: Jika server Anda berada di belakang proxy atau load balancer, pastikan komponen tersebut tidak mengubah badan permintaan atau header sebelum kode Anda menerimanya.

Uji webhook Anda

Gunakan server echo lokal untuk memeriksa permintaan POST mentah yang dikirim oleh DMS.

Simpan skrip berikut sebagai 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

Jalankan server pada port yang tersedia:
```
ruby print_http_body.rb 8000
```
Di Konsol DMS, konfigurasikan http://my.host:8000/ sebagai URL webhook. Untuk detailnya, lihat Konfigurasi informasi pribadi dan metode notifikasi.Konsol DMS baru

Pada kotak dialog Modify notification method, klik Test di sebelah kanan bidang URL webhook. DMS mengirim notifikasi uji ke titik akhir Anda. Server echo mencetak badan permintaan, yang tampak seperti berikut:

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

Jika server Anda menggunakan HTTP Basic Authentication, sertakan kredensial langsung di URL webhook:

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