Webhook

Webhook adalah URL yang ditentukan partner tempat platform RCS for Business memposting pesan dan peristiwa. URL ini bertindak 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 RCS for Business mengantrekan pesan untuk partner di satu antrean. Kegagalan webhook satu agen (tidak menampilkan 200) dapat memengaruhi pengiriman webhook semua agen lain di akun partner yang sama. Untuk mengetahui informasi selengkapnya, lihat Implikasi webhook tingkat agen.

Webhook partner dan webhook agen

Anda dapat mengonfigurasi webhook di tingkat partner atau tingkat agen.

• Webhook partner 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 mana pun yang tidak memiliki webhook sendiri.

Mengonfigurasi webhook agen

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

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

1. Buka Konsol Developer RCS for Business dan login dengan Akun Google partner RCS for Business Anda.
2. Klik agen Anda.
3. Klik Integrasi.

4. Di bagian Webhook, klik Konfigurasi.

   1. Di Endpoint webhook, masukkan URL webhook Anda yang dimulai dengan "https://".
   2. Di Token klien, tentukan nilai clientToken Anda. Anda memerlukannya untuk memverifikasi bahwa pesan yang Anda terima berasal dari Google.
   Catatan: Token klien Anda saat ini tidak dapat ditampilkan karena alasan keamanan. Untuk membuat token klien baru, masukkan nilai di kolom yang sesuai atau klik Refresh untuk membuat nilai acak.

5. Siapkan webhook Anda untuk menerima permintaan POST dengan payload JSON yang menyertakan parameter clientToken dan secret.

   {
     "clientToken":"YOURCLIENTTOKEN",
     "secret":"YOURSECRET"
   }
   

   Untuk memvalidasi permintaan, endpoint Anda harus menampilkan kode status HTTP 200 OK dengan nilai string mentah parameter secret di isi respons.

   Contoh konfigurasi webhook

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

     {
     "clientToken":"YOURCLIENTTOKEN",
     "secret":"YOURSECRET"
     }
     

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

     // clientToken from Configure
     const myClientToken = "YOURCLIENTTOKEN";
   
     // Example endpoint
     app.post("/rbm-webhook", (req, res) => {
       // Use the X-Goog-Webhook-Type header to route requests
       const webhookType = req.header('X-Goog-Webhook-Type');
   
       if (webhookType === 'verification') {
         const msg = req.body;
         if (msg.clientToken === myClientToken) {
             res.status(200).send(msg.secret);
             return;
         }
       }
       res.send(400);
       // Handle other webhook types
     });
     

6. Di Konsol Developer, klik Verifikasi. Setelah Anda mengklik Verifikasi, Google akan mengirimkan permintaan POST ke webhook Anda dengan clientToken dan secret sebagai parameter dalam isi permintaan. Saat RCS for Business memverifikasi webhook Anda, dialog akan ditutup.

Mengidentifikasi jenis permintaan

Guna mengidentifikasi jenis permintaan untuk semua permintaan yang masuk ke webhook Anda, gunakan header X-Goog-Webhook-Type.

Header dapat memiliki nilai berikut:

• verification: Digunakan untuk proses verifikasi endpoint awal.
• message_callback: Digunakan untuk peristiwa terkait pesan, seperti notifikasi pengetikan atau pengiriman dan pesan masuk dari pengguna.
• agent_callback: Digunakan untuk peristiwa administratif khusus agen, seperti perubahan status peluncuran agen.

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 base64 payload RCS for Business di elemen message.body permintaan.
3. Dengan menggunakan token klien webhook Anda (yang Anda tentukan saat menyiapkan webhook) sebagai kunci, buat SHA512 HMAC 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 mengirim pesan tersebut.

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

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

Node.js

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

    if (headerHash === genHash) {
      const userEvent = JSON.parse(userEventString);
      const webhookType = req.header('X-Goog-Webhook-Type');

      // Route based on the header type
      if (webhookType === 'message_callback') {
        handleMessage(userEvent);
      } else if (webhookType === 'agent_callback') {
        handleAgentEvent(userEvent);
      }
    } else {
      console.log('Hash mismatch - ignoring message');
      res.sendStatus(401);
      return;
    }
  }

  res.sendStatus(200);
  

Penanganan pesan

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

Developer harus memperhatikan 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 mereka, waktu tunggu habis, atau kegagalan upstream. Hal yang perlu dipertimbangkan mencakup:

• Pastikan perlindungan DDoS Anda dikonfigurasi untuk menangani kecepatan notifikasi webhook yang diharapkan.
• Pastikan resource seperti kumpulan koneksi database tidak habis dan menghasilkan waktu tunggu habis 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. Error atau penundaan selama pemrosesan dapat memengaruhi kode hasil webhook:

Perilaku saat kegagalan pengiriman

Jika webhook Anda menampilkan status selain 200 OK, platform RCS for Business akan menggunakan mekanisme backoff dan percobaan ulang untuk mengirim ulang data. Artinya, sistem secara progresif meningkatkan penundaan antara setiap upaya pengiriman, yang pada 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 di bawah satu akun partner berbagi satu antrean. Karena hal ini, kegagalan dalam 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 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 tampilkan 200 OK: Webhook harus menerima pesan, menyimpannya dalam antrean lokal, dan menampilkan respons 200 OK dalam waktu kurang dari lima detik.
• Pisahkan pemrosesan: Gunakan pekerja latar belakang terpisah untuk memproses logika pesan dari antrean lokal.
• Pantau agen pengujian: Perlakukan agen pengembangan sebagai agen produksi, karena agen pengembangan 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 pengambil yang dipicu pengguna dan pengambil yang dipicu pengguna Google.

Langkah berikutnya

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