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 ş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 aracı webhook'ları

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

İş ortağı webhook'unuz, sürdürdüğünüz her temsilci için geçerlidir. Temsilcileriniz benzer davranışlara sahipse 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 aracı işletiyorsanız her aracı için farklı bir webhook ayarlayabilirsiniz.

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.

Aracı webhook'u yapılandırma

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

Business Communications Developer Console'u açın ve RBM iş ortağı Google Hesabınızla oturum açın.
Ajanınızı tıklayın.
Integrations'ı (Entegrasyonlar) tıklayın.
Webhook için Yapılandır'ı tıklayın.
Webhook uç nokta URL'si alanına "https://" ile başlayan webhook URL'nizi girin.
clientToken değerinizi not edin. Bu kod, aldığınız iletilerin Google'dan geldiğini doğrulamanız için gereklidir.
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);
});
```
Developer Console'da Doğrula'yı tıklayın. RBM, 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:

İletinin X-Goog-Signature üstbilgisini ayıklayın. Bu, ileti gövdesi yükünün karma oluşturulmuş, Base64 kodlu bir kopyasıdır.
İsteğin message.body öğesindeki RBM yükünün Base64 kodunu çözün.
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.
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:

Senkronize webhook işleme

Teslimat 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ını kullanır. RBM, yeniden denemeler arasındaki bekleme süresini en fazla 600 saniyeye çıkarır. Yeniden denemeler 7 gün boyunca devam eder. Bu sürenin sonunda ileti bırakılır.

Temsilci düzeyinde webhook'ların etkileri

RBM, bir iş ortağı için mesajları tek bir kuyrukta sıraya alır. Bir iş ortağı, aracı düzeyinde webhook'lar kullanıyorsa bir webhook'un başarısız olmasının diğer webhook'lara teslimatı etkileyeceğini unutmaması gerekir. Diğer aracılara ait webhook'lar, başarısız olan bir mesajın geri çekilme süresi boyunca çağrılır. Ancak, başarısız iletiler yeniden deneme için sıraya alındıkça genel teslimat oranları düşer ve diğer aracıların etkilenir.

Geliştiricilerin bu modeli anlaması ve buna göre kod yazması önemlidir. Mümkün olduğunca mesajları kabul edip işlenmek üzere sıraya alarak hata döndürme olasılığını en aza indirmeleri gerekir.

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.

Dialogflow