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.

Webhook partner dan webhook agen

Anda dapat mengonfigurasi webhook di tingkat partner atau di tingkat agen.

Webhook partner Anda berlaku untuk setiap agen yang Anda kelola. Jika agen Anda memiliki perilaku serupa, atau jika Anda hanya memiliki satu agen, gunakan webhook partner.
Webhook agen berlaku untuk setiap agen. Jika 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

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

Buka Business Communications Developer Console, lalu login dengan Akun Google partner RBM Anda.
Klik agen Anda.
Klik Integrasi.
Untuk Webhook, klik Configure.
Untuk URL endpoint webhook, masukkan URL webhook Anda yang diawali dengan "https://".
Catat nilai clientToken Anda. Anda memerlukannya untuk memverifikasi bahwa pesan yang Anda terima berasal dari Google.
Konfigurasikan webhook Anda untuk menerima permintaan POST dengan parameter clientToken yang ditentukan dan kirim 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"
}
```
webhook Anda harus mengonfirmasi nilai clientToken dan, jika clientToken benar, tampilkan 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);
});
```
Di Konsol Play, 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:

Ekstrak header X-Goog-Signature pesan. Ini adalah salinan payload isi pesan yang di-hash dan dienkode base64.
Dekode payload RBM dalam elemen message.body permintaan menggunakan base-64.
Dengan menggunakan token klien webhook (yang Anda tentukan saat menyiapkan webhook) sebagai kunci, buat HMAC SHA512 dari byte payload pesan yang didekode base-64 dan encode hasilnya dalam base64.
Bandingkan hash X-Goog-Signature dengan hash yang Anda buat.
- Jika hash cocok, Anda telah mengonfirmasi bahwa Google mengirim pesan.
- Jika hash tidak cocok, periksa proses hashing Anda pada pesan yang dikenal baik.
  
  Jika proses hashing Anda berfungsi dengan benar dan Anda menerima pesan yang menurut Anda dikirim kepada Anda secara menipu, 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 memperhatikan bahwa mengirim pesan dengan frekuensi tinggi akan menghasilkan notifikasi webhook dengan frekuensi tinggi dan harus mendesain kode mereka untuk memastikan mereka dapat menggunakan notifikasi dengan frekuensi yang diharapkan. Penting bagi developer untuk mempertimbangkan situasi yang dapat menyebabkan respons kegagalan, termasuk respons 500 dari penampung web, waktu tunggu habis, atau kegagalan upstream. Hal-hal yang perlu dipertimbangkan meliputi:

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

Perilaku saat pengiriman gagal

RBM menggunakan mekanisme backoff dan percobaan ulang saat menerima respons selain 200 OK dari panggilan webhook. RBM akan meningkatkan waktu tunggu antar-percobaan ulang hingga maksimum 600 detik. Percobaan ulang akan berlanjut selama 7 hari, setelah itu pesan akan dihapus.

Implikasi webhook tingkat agen

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

Developer harus memahami model dan kode ini dengan benar - sebisa mungkin, menerima pesan dan mengantrekannya untuk diproses guna meminimalkan peluang menampilkan kegagalan.

Langkah berikutnya

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