Webhook'lar

Webhook, aracınızın mesajlara ve etkinliklere nasıl yanıt vermesi gerektiğini belirten, iş ortağı tarafından oluşturulan bir HTTPS geri çağırmasıdır. Webhook'unuzu yapılandırdıktan sonra mesaj almaya ve etkinlikleri 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, yönettiğiniz her temsilci için geçerlidir. Temsilcileriniz benzer davranışlar sergiliyorsa veya yalnızca bir aracınız varsa partner webhook'u kullanın.
  • Temsilci web kancaları, bağımsız aracılar için geçerlidir. Farklı davranışlara sahip birden fazla aracı çalıştırıyorsanız her aracı için farklı bir webhook ayarlayabilirsiniz.

Hem iş ortağı webhook'u hem de aracı webhook'u yapılandırdıysanız aracı webhook, kendi aracısına göre öncelikli olur. İş ortağı webhook'u ise kendi webhook'una sahip olmayan tüm aracılar için geçerli olur.

Aracı webhook'u yapılandırma

Temsilcinize gönderilen mesajları iş ortağı webhook'unuzdan alırsınız. Belirli bir temsilcinin mesajlarının farklı bir webhook'a ulaşmasını istiyorsanız aracı 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. Integrations'ı (Entegrasyonlar) tıklayın.
  4. Webhook için Yapılandır'ı tıklayın.
  5. Webhook uç nokta URL'si için "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 kimliği kullanmanız gerekir.

  7. Webhook'unuzu, belirtilen clientToken parametresiyle bir POST isteğini kabul edecek ve yanıt gövdesi 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'unuz aşağıdaki gövde içeriğine sahip bir POST isteği alırsa

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

    webhook'unuz clientToken değerini onaylamalı ve clientToken doğruysa yanıt gövdesi olarak 1234567890 değerini içeren 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. Geliştirici Konsolu'nda Doğrula'yı tıklayın. RBM webhook'unuzu doğruladığında iletişim kutusu kapanır.

Gelen iletileri doğrulayın

Webhook'lar tüm gönderenlerden mesaj alabildiğinden, Google'ın gelen mesajları ileti içeriğini işlemeden önce gönderdiğini doğrulamanız gerekir.

Aldığınız mesajın Google tarafından gönderildiğini doğrulamak için aşağıdaki adımları uygulayın:

  1. İletinin X-Goog-Signature üstbilgisini çıkarın. Bu, mesaj gövdesi yükünün karma, base64 kodlu bir kopyasıdır.
  2. İsteğin message.body öğesinde RBM yükünü Base-64 kodunu çözün.
  3. Webhook'unuzu oluştururken belirttiğiniz, webhook'unuzun istemci jetonunu anahtar olarak kullanarak temel 64 kodu çözülmüş mesaj yükünün baytlarının SHA512 HMAC'sini oluşturun ve sonucu base64 olarak kodlayın.
  4. X-Goog-Signature karmasını, oluşturduğunuz karmayla karşılaştırın.
    • Karmalar eşleşiyorsa iletiyi Google'ın gönderdiğini onaylamış olursunuz.

    • Karmalar eşleşmezse bilinen iyi bir iletide karma oluşturma işleminizi kontrol edin.

      Karma oluşturma süreciniz doğru şekilde çalışıyorsa ve size hileli şekilde 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);

Mesaj işleme

Bir webhook'tan 200 OK dışında herhangi bir şeyin döndürülmesi teslim hatası olarak kabul edilir.

Geliştiriciler yüksek hızlarda mesaj göndermenin yüksek hızlarda webhook bildirimleri oluşturacağını dikkate almalı ve kodlarını beklenen oranda tüketebilmelerini sağlayacak şekilde tasarlamalıdır. Geliştiricilerin, web kapsayıcılarından gelen 500 yanıtları, zaman aşımları veya yukarı akış hataları gibi hata yanıtlarına neden olabilecek durumları dikkate almaları önemlidir. Göz önünde bulundurulması gereken noktalar şunlardır:

  • DDoS korumalarınızın, beklenen webhook bildirimleri hızını işleyecek şekilde yapılandırıldığından emin olun.
  • Veritabanı bağlantı havuzları gibi kaynakların tükenmediğinden emin olun ve zaman aşımları veya 500 yanıtları üretin.

Teslimat hatasındaki davranış

RBM, bir webhook çağrısından 200 OK dışında bir yanıt aldığında geri alma ve yeniden deneme mekanizması kullanır. RBM, yeniden denemeler arasındaki bekleme süresini maksimum 600 saniyeye kadar yükseltir. Kullanımdan kaldırma işlemleri 7 gün boyunca devam eder ve bu sürenin ardından ileti silinir.

Temsilci düzeyinde webhook'ların etkileri

RBM, bir iş ortağı için mesajları bir sırada sıraya alır. Bir iş ortağının aracı düzeyinde webhook'lar kullandığı durumlarda, bir webhook'un arıza yapmasının diğer webhook'lara yayınlamayı etkileyeceğini unutmayın. Diğer aracılara ait webhook'lar, başarısız bir mesajın geri çekilme süresinde çağrılır. Ancak başarısız mesajlar, yeniden deneme için sıraya alındığında genel teslim hızları düşer ve diğer aracılar bu durumdan etkilenir.

Geliştiricilerin bu modeli ve kodu uygun şekilde anlaması önemlidir. Hata döndürme ihtimalini en aza indirmek için mesajları kabul etmek ve işlenmek üzere sıraya koymak gerekir.

Sonraki adımlar

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