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 uygulamanıza güvenli bir şekilde 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 ajan webhook'u yapılandırdıysanız belirli ajanında ajan webhook'u öncelikli olurken iş ortağı webhook'u kendi webhook'u olmayan tüm ajanlar için geçerli olur.

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 ajan webhook'u ayarlayın.

  1. RCS for Business Developer Console'u açın ve RCS for Business iş ortağı Google Hesabınızla oturum açın.
  2. Temsilcinizi tıklayın.
  3. Integrations'ı (Entegrasyonlar) tıklayın.

  4. Webhook bölümünde Yapılandır'ı tıklayın.

    1. Webhook uç noktası bölümüne "https://" ile başlayan webhook URL'nizi girin.
    2. İstemci jetonu bölümünde clientToken değerinizi belirtin. Aldığınız iletilerin Google'dan geldiğini doğrulamak için bu kodu kullanmanız gerekir.

  5. Webhook'unuzu, clientToken ve secret parametrelerini içeren bir JSON yüküyle POST isteklerini kabul edecek şekilde ayarlayın.

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

    İsteği doğrulamak için uç noktanız, yanıt gövdesinde secret parametresinin ham dize değeriyle birlikte bir HTTP 200 OK durumu kodu döndürmelidir.

    Örnek webhook yapılandırması

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

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

    Ardından, webhook'unuz clientToken değerini onaylamalı ve clientToken doğruysa yanıt gövdesi olarak YOURSECRET ile 200 OK yanıtını döndürmelidir:

      // 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. Developer Console'da Doğrula'yı tıklayın. Doğrula'yı tıkladıktan sonra Google, webhook'unuza bir POST isteği gönderir. İsteğin gövdesinde clientToken ve secret parametreleri bulunur. RCS for Business, webhook'unuzu doğruladığında iletişim kutusu kapanır.

İstek türlerini belirleme

Webhook'unuza gelen tüm isteklerin türünü belirlemek için <code>X-Goog-Webhook-Type</code> başlığını kullanın.X-Goog-Webhook-Type

Başlık aşağıdaki değerleri içerebilir:

  • verification: İlk uç nokta doğrulama sürecinde kullanılır.
  • message_callback: Yazma veya teslimat bildirimleri ve kullanıcılardan gelen iletiler gibi mesajlarla ilgili etkinlikler için kullanılır.
  • agent_callback: Temsilciye özgü yönetim etkinlikleri (ör. temsilci başlatma durumu değişiklikleri) için kullanılı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 karma değerini oluşturduğunuz karma değerle karşılaştırın.
    • Karma değerler 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
    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);

İ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ı gibi başarısızlık yanıtlarına 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ı durumundaki 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.

Aracı 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 temsilciler için 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 sürede 200 OK yanıtını döndürmelidir.
  • İşlemi ayırma: Yerel kuyruktaki mesaj mantığını işlemek için ayrı arka plan çalışanları kullanın.
  • Test aracılarını izleme: Geliştirme aracıları da başarısız olmaları durumunda paylaşılan iş ortağı sırasını engelleyebileceğinden bunları üretim aracıları gibi değerlendirin.
  • 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 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ümanları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