Webhook

Webhook adalah URL yang ditentukan partner tempat platform RBM memposting pesan dan peristiwa. URL ini berfungsi sebagai endpoint yang menerima permintaan POST HTTPS yang berisi data tentang peristiwa. Artinya, data dikirim ke aplikasi Anda dengan aman melalui HTTPS.

URL webhook mungkin terlihat seperti ini: https://[your company name].com/api/rbm-events. Setelah mengonfigurasi webhook, Anda dapat mulai menerima pesan dan peristiwa.

Peringatan: Perhatikan bahwa RBM mengantrekan pesan untuk partner di satu antrean. Kegagalan webhook salah satu agen (tidak menampilkan 200) dapat memengaruhi pengiriman webhook semua agen lainnya di akun partner yang sama. Informasi selengkapnya: Implikasi webhook tingkat agen.

Webhook partner dan webhook agen

Anda dapat mengonfigurasi webhook di tingkat partner atau tingkat agen.

• Webhook partner Anda berlaku untuk setiap agen yang Anda kelola. Jika agen Anda memiliki perilaku yang serupa, atau jika Anda hanya memiliki satu agen, gunakan webhook partner.
• Webhook agen berlaku untuk setiap agen. Jika Anda mengoperasikan beberapa agen dengan perilaku yang berbeda, Anda dapat menetapkan webhook yang berbeda untuk setiap agen.

Jika Anda telah mengonfigurasi webhook partner dan webhook agen, webhook agen akan diprioritaskan pada agen tertentu, sedangkan webhook partner berlaku untuk agen yang tidak memiliki webhook sendiri.

Mengonfigurasi webhook agen

Catatan: Untuk membuat integrasi webhook menggunakan RBM Management API, lihat dokumentasi Membuat integrasi webhook.

Anda menerima pesan yang dikirim ke agen Anda di webhook partner Anda. Jika Anda ingin pesan untuk agen tertentu tiba di webhook yang berbeda, tetapkan webhook agen.

1. Buka Business Communications Developer Console dan login dengan Akun Google partner RBM Anda.
2. Klik agen Anda.
3. Klik Integrations.
4. Untuk Webhook, klik Konfigurasi.
5. Untuk URL endpoint webhook, masukkan URL webhook Anda yang dimulai dengan "https://".
6. Catat nilai clientToken Anda. Anda memerlukannya untuk memverifikasi bahwa pesan yang Anda terima berasal dari Google.

7. Konfigurasi webhook Anda untuk menerima permintaan POST dengan parameter clientToken yang ditentukan dan mengirim respons 200 OK dengan nilai teks biasa dari parameter secret sebagai isi respons.

   Misalnya, jika webhook Anda menerima permintaan POST dengan konten isi berikut

   {
     "clientToken":"SJENCPGJESMGUFPY",
     "secret":"1234567890"
   }
   

   maka webhook Anda harus mengonfirmasi nilai clientToken dan, jika clientToken benar, menampilkan respons 200 OK dengan 1234567890 sebagai isi respons:

   // clientToken from Configure
   const myClientToken = "SJENCPGJESMGUFPY";
   
   // Example endpoint
   app.post("/rbm-webhook", (req, res) => {
     const msg = req.body;
     if (msg.clientToken === myClientToken) {
         res.status(200).send(msg.secret);
         return;
     }
     res.send(400);
   });
   

8. Di Konsol Developer, klik Verifikasi. Saat RBM memverifikasi webhook Anda, dialog akan ditutup.

Memverifikasi pesan masuk

Karena webhook dapat menerima pesan dari pengirim mana pun, Anda harus memverifikasi bahwa Google mengirim pesan masuk sebelum memproses konten pesan.

Untuk memverifikasi bahwa Google mengirim pesan yang Anda terima, ikuti langkah-langkah berikut:

1. Ekstrak header X-Goog-Signature pesan. Ini adalah salinan payload isi pesan yang di-hash dan dienkode base64.
2. Dekode payload RBM yang dienkode menggunakan Base64 dalam elemen message.body permintaan.
3. Dengan menggunakan token klien webhook Anda (yang Anda tentukan saat menyiapkan webhook), buat HMAC SHA512 dari byte payload pesan yang didekode base64 dan enkode base64 hasilnya.
4. Bandingkan hash X-Goog-Signature dengan hash yang Anda buat.
   • Jika hash cocok, Anda telah mengonfirmasi bahwa Google mengirimkan pesan tersebut.

   • Jika hash tidak cocok, periksa proses hashing Anda pada pesan yang diketahui baik.

     Jika proses hashing Anda berfungsi dengan benar dan Anda menerima pesan yang menurut Anda dikirimkan kepada Anda secara curang, hubungi kami.

Node.js

  if ((requestBody.hasOwnProperty('message')) && (requestBody.message.hasOwnProperty('data'))) {
    // Validate the received hash to ensure the message came from Google RBM
    let userEventString = Buffer.from(requestBody.message.data, 'base64');
    let hmac = crypto.createHmac('sha512', CLIENT_TOKEN);
    let data = hmac.update(userEventString);
    let genHash = data.digest('base64');
    let headerHash = req.header('X-Goog-Signature');

    if (headerHash === genHash) {
      let userEvent = JSON.parse(userEventString);

      console.log('userEventString: ' + userEventString);
      handleMessage(userEvent);
    } else {
      console.log('hash mismatch - ignoring message');
    }
  }

  res.sendStatus(200);
  

Penanganan pesan

Menampilkan apa pun selain 200 OK dari webhook dianggap sebagai kegagalan pengiriman.

Developer harus ingat bahwa pengiriman pesan dengan kecepatan tinggi akan menghasilkan notifikasi webhook dengan kecepatan tinggi dan harus mendesain kode mereka untuk menangani notifikasi dengan kecepatan yang diharapkan. Developer harus mempertimbangkan situasi yang dapat menyebabkan respons kegagalan, termasuk respons 500 dari penampung web, waktu tunggu habis, atau kegagalan upstream. Hal-hal yang perlu dipertimbangkan mencakup:

• Verifikasi bahwa perlindungan DDoS Anda dikonfigurasi untuk menangani kecepatan notifikasi webhook yang diharapkan.
• Pastikan resource seperti kumpulan koneksi database tidak habis dan menghasilkan waktu tunggu atau respons 500.

Developer harus mendesain sistem mereka sehingga pemrosesan peristiwa RBM terjadi secara asinkron dan tidak mencegah webhook menampilkan 200 OK.

Penting untuk tidak memproses peristiwa RBM dalam webhook itu sendiri. Setiap error atau penundaan selama pemrosesan dapat memengaruhi kode yang ditampilkan webhook:

Perilaku saat pengiriman gagal

RBM menggunakan mekanisme mundur dan coba lagi saat menerima respons selain 200 OK dari panggilan webhook. RBM akan menambah waktu tunggu di antara percobaan ulang hingga maksimum 600 detik. Percobaan ulang akan berlanjut selama 7 hari, setelah itu pesan akan dibatalkan.

Implikasi webhook tingkat agen

RBM mengantrekan pesan untuk partner dalam satu antrean. Jika partner menggunakan webhook tingkat agen, penting untuk diingat bahwa kegagalan satu webhook akan memengaruhi pengiriman ke webhook lainnya. Webhook milik agen lain akan dipanggil selama periode penundaan pesan yang gagal. Namun, karena pesan yang gagal diantrekan untuk dicoba lagi, rasio pengiriman secara keseluruhan akan menurun dan agen lain akan terpengaruh.

Developer harus memahami model ini dan membuat kode yang sesuai - sejauh mungkin, menerima pesan dan mengantrekannya untuk diproses guna meminimalkan peluang kegagalan.

Langkah berikutnya

Setelah mengonfigurasi webhook, agen Anda dapat menerima pesan dari perangkat pengujian Anda. Kirim pesan untuk memvalidasi penyiapan Anda.