Webhook

Webhook adalah URL yang ditentukan partner tempat platform RCS for Business 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 secara 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 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

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.

Buka Konsol Developer Business Communications dan login dengan Akun Google partner RCS for Business Anda.
Klik agen Anda.
Klik Integrations.
Untuk Webhook, klik Konfigurasi.
Untuk URL endpoint webhook, masukkan URL webhook Anda yang dimulai dengan "https://".
Catat nilai clientToken Anda. Anda memerlukannya untuk memverifikasi bahwa pesan yang Anda terima berasal dari Google.
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);
});
```
Di Konsol Developer, klik Verifikasi. Saat RCS untuk Bisnis 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.
Lakukan dekode Base-64 pada payload RCS for Business dalam elemen message.body permintaan.
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.
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 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 gagal, 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.

Pemrosesan webhook asinkron

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

Pemrosesan webhook sinkron

Perilaku saat pengiriman gagal

Jika webhook Anda menampilkan status selain 200 OK, platform RCS untuk Bisnis akan menggunakan mekanisme jeda dan coba lagi untuk mengirim ulang data. Artinya, sistem akan meningkatkan penundaan secara progresif di antara setiap upaya pengiriman, hingga akhirnya mencapai frekuensi maksimum satu percobaan ulang setiap 10 menit untuk setiap pesan yang tertunda. Siklus percobaan ulang berlanjut selama tujuh hari, setelah itu pesan akan dihapus secara permanen.

Implikasi webhook tingkat agen

RCS for Business mengantrekan pesan untuk partner di satu antrean. Semua agen dalam satu akun partner berbagi satu antrean. Oleh karena itu, kegagalan di satu webhook dapat memblokir seluruh antrean, sehingga mencegah peristiwa pengguna untuk semua agen mencapai partner.

Beberapa pesan yang tidak dikonfirmasi dapat menyebabkan lonjakan besar dalam peristiwa percobaan ulang. Misalnya, jika agen tidak mengonfirmasi 1.600 tanda terima pengiriman, dan frekuensi percobaan ulang mencapai batas 10 menit, hal ini dapat menghasilkan sekitar 230.000 potensi error per hari:

1.600 pesan × 6 percobaan ulang per jam × 24 jam per hari = sekitar 230.000 error per hari

Volume percobaan ulang ini dapat memblokir antrean Pub/Sub bersama dan menyebabkan penundaan yang signifikan dalam menerima peristiwa pengguna untuk semua kampanye partner.

Praktik terbaik

Untuk mengamankan keandalan traffic produksi dan menghindari pemblokir antrean, ikuti praktik terbaik berikut:

Segera menampilkan 200 OK: Webhook harus menerima pesan, menyimpannya dalam antrean lokal, dan menampilkan respons 200 OK dalam waktu kurang dari lima detik.
Memisahkan pemrosesan: Gunakan pekerja latar belakang terpisah untuk memproses logika pesan dari antrean lokal.
Memantau agen pengujian: Perlakukan agen pengembangan sebagai agen produksi, karena agen tersebut juga dapat memblokir antrean partner bersama jika gagal.
Akun khusus untuk pengujian: Sebaiknya gunakan satu akun developer untuk agen produksi dan akun developer khusus untuk agen pengujian.
Verifikasi traffic Google: Gunakan DNS Terbalik atau header X-Goog-Signature, bukan daftar yang diizinkan IP tetap, karena Google menggunakan IP anycast dinamis. Untuk mengetahui informasi selengkapnya tentang verifikasi manual dan mengidentifikasi rentang IP Google, lihat dokumentasi Memverifikasi permintaan Google dan khususnya file JSON untuk pengambilan yang dipicu pengguna dan pengambilan yang dipicu pengguna Google.

Langkah berikutnya

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

Berikutnya

Dialogflow