Webhook'lar

Webhook, RBM 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 şu şekilde görünebilir: https://[your company name].com/api/rbm-events. Webhook'ınızı yapılandırdıktan sonra mesaj ve etkinlik almaya başlayabilirsiniz.

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

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

• İş ortağı webhook'ınız, yönettiğiniz her temsilci için geçerlidir. Temsilcilerinizin davranışı benzerse veya yalnızca bir temsilciniz varsa iş ortağı webhook'unu kullanın.
• Temsilci webhook'ları tek tek temsilciler için geçerlidir. Farklı davranışlara sahip birden fazla temsilci kullanıyorsanız her temsilci için farklı bir webhook ayarlayabilirsiniz.

Hem iş ortağı webhook'u hem de temsilci webhook'u yapılandırdıysanız temsilci webhook'u ilgili temsilci için öncelikli olur. İş ortağı webhook'u ise kendi webhook'u olmayan tüm temsilciler için geçerli olur.

Temsilci webhook'u yapılandırma

Not: RBM Management API'yi kullanarak webhook entegrasyonu oluşturmak için Webhook entegrasyonu oluşturma dokümanlarına bakın.

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

1. Business Communications Developer Console'u açın ve RBM iş ortağı Google Hesabınızla oturum açın.
2. Temsilcinizi tıklayın.
3. 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. Aldığınız mesajların Google'dan geldiğini doğrulamak için bu numaraya ihtiyacınız vardır.

7. Webhook'unuzu, belirtilen clientToken parametresini içeren bir POST isteğini kabul edecek ve yanıt metni olarak secret parametresinin düz metin değerini içeren bir 200 OK yanıtı gönderecek şekilde yapılandırın.

   Örneğin, webhook'ınız aşağıdaki body içeriğine sahip bir POST isteği alırsa

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

   ise webhook'unuz clientToken değerini onaylamalı ve clientToken doğruysa yanıt gövdesinde 1234567890 bulunan 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. Developers Console'da Doğrula'yı tıklayın. RBM, webhook'ınızı 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 Google'ın gelen mesajları gönderdiğini doğrulamanız gerekir.

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

1. İletinin X-Goog-Signature başlığını çıkarın. Bu, ileti gövdesi yükünün karma oluşturma işlemi uygulanmış ve base64 kodlu bir kopyasıdır.
2. İsteğin message.body öğesindeki RBM yükünün Base64 kodunu çözme.
3. Anahtar olarak webhook'ınızın istemci jetonunu (webhook'unuzu ayarlarken belirttiğiniz) 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 karmayla karşılaştırın.
   • Karmalar eşleşirse mesajın Google tarafından gönderildiğini onaylamış olursunuz.

   • Karma oluşturma işlemleri eşleşmiyorsa iyi bilinen bir mesajda karma oluşturma işleminizi kontrol edin.

     Karma oluşturma işleminiz düzgün çalışıyorsa ve size sahtekarlık amaçlı 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);
  

Mesajları işleme

Bir webhook'dan 200 OK dışında bir şey döndürülmesi, teslimat hatası olarak kabul edilir.

Geliştiriciler, yüksek hızda mesaj göndermenin yüksek hızda webhook bildirimi oluşturacağını göz önünde bulundurmalı ve kodlarını, bildirimleri beklenen hızda kullanabilecekleri şekilde tasarlamalıdır. Geliştiricilerin, web kapsayıcılarından gelen 500 yanıtları, zaman aşımları veya yayın öncesi hatalar da dahil olmak üzere başarısızlık yanıtlarına neden olabilecek durumları göz önünde bulundurması önemlidir. Göz önünde bulundurulması gereken noktalar:

• DDoS korumalarınızın, beklenen webhook bildirim hızını karşılayacak şekilde yapılandırıldığından emin olun.
• Veritabanı bağlantı havuzları gibi kaynakların tükenmediğinden ve zaman aşımı veya 500 yanıtları oluşturmadığından emin olun.

Yayınlama hatası durumunda davranış

RBM, bir webhook çağrısından 200 OK dışında bir yanıt aldığında geri çekilme ve yeniden deneme mekanizması kullanır. RBM, yeniden denemelerin arasında beklediği süreyi en fazla 600 saniyeye kadar artırır. Yeniden deneme işlemi 7 gün boyunca devam eder. Bu sürenin ardından mesaj bırakılır.

Temsilci düzeyinde webhook'ların sonuçları

RBM, bir iş ortağı için mesajları tek bir kuyrukta sıraya koyar. Bir iş ortağının temsilci düzeyinde webhook'lar kullandığı durumlarda, bir webhook'un başarısız olmasının diğer webhook'lara yapılan yayını etkileyeceğini unutmayın. Diğer temsilcilere ait webhook'lar, başarısız bir mesajın bekleme süresi sırasında çağrılır. Ancak, başarısız iletiler yeniden deneme için sıraya alındığında genel teslimat oranları düşer ve diğer temsilciler etkilenir.

Geliştiricilerin bu modeli anlaması ve buna göre kod yazması önemlidir. Mümkün olduğunca, hata döndürme olasılığını en aza indirmek için mesajları kabul edip işleme için sıraya koymaları gerekir.

Sonraki adımlar

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