Webhook'lar

Webhook, RCS for Business platformunun mesajlar ve etkinlikler yayınladığı, iş ortağı tarafından belirtilen bir URL'dir. Bu URL, etkinliklerle ilgili veriler içeren HTTPS POST isteklerini alan bir uç nokta görevi görür. Bu, verilerin HTTPS üzerinden güvenli bir şekilde uygulamanıza gönderildiği anlamına gelir.

Webhook URL'si şuna benzer bir şekilde görünebilir: https://[your company name].com/api/rbm-events. Webhook'unuzu yapılandırdıktan sonra mesaj ve etkinlik almaya başlayabilirsiniz.

İş ortağı webhook'ları ve temsilci webhook'ları

Webhook'unuzu iş ortağı düzeyinde veya temsilci düzeyinde yapılandırabilirsiniz.

Hem iş ortağı webhook'u hem de temsilci webhook'u yapılandırdıysanız temsilci webhook'u, kendi webhook'u olmayan tüm temsilciler için geçerli olan iş ortağı webhook'una göre önceliklidir.

Ajan webhook'u yapılandırma

Temsilcinize gönderilen mesajları iş ortağı webhook'unuzda alırsınız. Belirli bir ajanın mesajlarının farklı bir webhook'a ulaşmasını istiyorsanız bir ajan webhook'u ayarlayın.

  1. Business Communications Developer Console'u açın ve Business için RCS iş ortağı Google Hesabınızla oturum açın.
  2. Temsilcinizi tıklayın.
  3. Integrations'ı (Entegrasyonlar) tıklayın.
  4. Webhook için Yapılandır'ı tıklayın.
  5. Webhook uç nokta URL'si alanına "https://" ile başlayan webhook URL'nizi girin.
  6. clientToken değerinizi not edin. Bu kod, aldığınız iletilerin Google'dan geldiğini doğrulamanız için gereklidir.

  7. Webhook'unuzu, belirtilen clientToken parametresiyle bir POST isteğini kabul edecek şekilde yapılandırın ve yanıt gövdesi olarak secret parametresinin düz metin değeriyle bir 200 OK yanıtı gönderin.

    Örneğin, webhook'unuz aşağıdaki gövde içeriğine sahip bir POST isteği alıyorsa

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

    ise webhook'unuz clientToken değerini onaylamalı ve clientToken doğruysa yanıt gövdesi olarak 1234567890 ile birlikte bir 200 OK yanıtı döndürmelidir:

    // 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. Developer Console'da Doğrula'yı tıklayın. RCS for Business, webhook'unuzu doğruladığında iletişim kutusu kapanır.

Gelen iletileri doğrulama

Webhook'lar herhangi bir gönderenden mesaj alabileceğinden, mesaj içeriğini işlemeden önce gelen mesajların Google tarafından gönderildiğini doğrulamanız gerekir.

Google'ın gönderdiği bir mesajı aldığınızı doğrulamak için aşağıdaki adımları uygulayın:

  1. İletinin X-Goog-Signature başlığını ayıklayın. Bu, e-posta mesajı yükünün karma oluşturulmuş, Base64 kodlu bir kopyasıdır.
  2. İsteğin message.body öğesindeki RCS for Business yükünü Base64 ile kod çözün.
  3. Webhook'unuzun istemci jetonunu (webhook'unuzu ayarlarken belirttiğiniz) anahtar olarak kullanarak, base64 kodu çözülmüş ileti yükünün baytlarının SHA512 HMAC'sini oluşturun ve sonucu base64 ile kodlayın.
  4. X-Goog-Signature karmasını oluşturduğunuz karma ile karşılaştırın.
    • Karma değerleri eşleşirse Google'ın mesajı gönderdiğini onaylamış olursunuz.

    • Karma değerleri eşleşmiyorsa karma oluşturma işleminizi bilinen iyi bir mesaj üzerinde kontrol edin.

      Karma oluşturma işleminiz doğru şekilde çalışıyorsa ve size sahtekarlık amacıyla gönderildiğini düşündüğünüz bir mesaj alırsanız bize ulaşın.

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);

İleti işleme

Webhook'tan 200 OK dışında bir değer döndürmek teslimat hatası olarak kabul edilir.

Geliştiriciler, yüksek sıklıkta mesaj göndermenin yüksek sıklıkta webhook bildirimleri oluşturacağını unutmamalı ve kodlarını bildirimleri beklenen sıklıkta işleyecek şekilde tasarlamalıdır. Geliştiricilerin, web kapsayıcılarından gelen 500 yanıtları, zaman aşımları veya yukarı akış hataları da dahil olmak üzere başarısız yanıtların verilmesine neden olabilecek durumları göz önünde bulundurmaları önemlidir. Dikkate alınması gereken noktalar:

  • DDoS korumalarınızın, beklenen webhook bildirimi hızını işleyecek şekilde yapılandırıldığını doğrulayın.
  • Veritabanı bağlantı havuzları gibi kaynakların tükenmediğini ve zaman aşımları veya 500 yanıtları oluşturmadığını doğrulayın.

Geliştiriciler, sistemlerini RBM etkinliklerinin işlenmesi eşzamansız olarak gerçekleşecek ve webhook'un 200 OK döndürmesini engellemeyecek şekilde tasarlamalıdır.

Eşzamansız webhook işleme

RBM etkinliğinin webhook'un kendisinde işlenmemesi önemlidir. İşleme sırasında oluşan herhangi bir hata veya gecikme, webhook dönüş kodunu etkileyebilir:

Eşzamanlı webhook işleme

Teslimat hatası durumunda davranış

Webhook'unuz 200 OK durumu dışında bir şey döndürürse İşletmeler için RCS platformu, verileri yeniden teslim etmek için geri çekilme ve yeniden deneme mekanizmasını kullanır. Bu durumda sistem, her teslimat denemesi arasındaki gecikmeyi kademeli olarak artırır ve sonunda bekleyen her ileti için 10 dakikada bir yeniden deneme olmak üzere maksimum sıklığa ulaşır. Yeniden deneme döngüsü yedi gün boyunca devam eder. Bu sürenin sonunda mesaj kalıcı olarak silinir.

Ajan düzeyinde webhook'ların etkileri

RCS for Business, bir iş ortağına ait mesajları tek bir kuyrukta sıraya alır. Tek bir iş ortağı hesabı altındaki tüm temsilciler tek bir kuyruğu paylaşır. Bu nedenle, bir webhook'taki hata tüm kuyruğu engelleyebilir ve tüm temsilcilerle ilgili kullanıcı etkinliklerinin iş ortağına ulaşmasını önleyebilir.

Onaylanmamış çok sayıda mesaj, yeniden deneme etkinliklerinde büyük bir artışa neden olabilir. Örneğin, bir aracı 1.600 teslimat makbuzunu onaylamazsa ve yeniden deneme sıklığı 10 dakikalık sınıra ulaşırsa günde yaklaşık 230.000 olası hata oluşturabilir:

1.600 mesaj × saatte 6 yeniden deneme × günde 24 saat = günde yaklaşık 230.000 hata

Bu kadar çok yeniden deneme, paylaşılan Pub/Sub kuyruğunu engelleyebilir ve bir iş ortağının tüm kampanyaları için kullanıcı etkinliklerinin alınmasında önemli gecikmelere neden olabilir.

En iyi uygulamalar

Üretim trafiğinizin güvenilirliğini sağlamak ve kuyruk engelleyicilerden kaçınmak için aşağıdaki en iyi uygulamalardan yararlanın:

  • Hemen 200 OK döndürün: Web kancası mesajı almalı, yerel bir kuyrukta saklamalı ve beş saniyeden kısa bir süre içinde 200 OK yanıtını döndürmelidir.
  • İşlemeyi ayırma: Yerel kuyruktaki mesaj mantığını işlemek için ayrı arka plan çalışanları kullanın.
  • Test aracılarını izleyin: Geliştirme aracılarını üretim aracıları gibi değerlendirin. Çünkü başarısız olmaları durumunda paylaşılan iş ortağı sırasını da engelleyebilirler.
  • Test için özel hesaplar: Üretim aracıları için tercihen bir geliştirici hesabı, test aracıları için ise özel bir geliştirici hesabı kullanın.
  • Google trafiğini doğrulama: Google, dinamik anycast IP'ler kullandığından sabit IP izin verilenler listesi yerine ters DNS veya X-Goog-Signature üstbilgisini kullanın. Manuel doğrulama ve Google IP aralıklarını belirleme hakkında daha fazla bilgi için Google isteklerini doğrulama dokümanına ve özellikle kullanıcı tarafından tetiklenen alıcılar ile Google kullanıcı tarafından tetiklenen alıcılar için JSON dosyalarına bakın.

Sonraki adımlar

Webhook'unuzu yapılandırdıktan sonra temsilciniz, test cihazlarınızdan mesaj alabilir. Kurulumunuzu doğrulamak için mesaj gönderin.

Sonraki
Dialogflow