Webhooki

Webhook to podany przez partnera adres URL, pod którym platforma RBM publikuje wiadomości i zdarzenia. Ten adres URL działa jako punkt końcowy, który odbiera żądania HTTPS POST zawierające dane o zdarzeniach. Oznacza to, że dane są bezpiecznie wysyłane do aplikacji przez HTTPS.

Adres URL webhooka może wyglądać tak: https://[your company name].com/api/rbm-events. Po skonfigurowaniu webhooka możesz zacząć otrzymywać wiadomości i zdarzenia.

Webhooki partnera i agenta

Webhooka możesz skonfigurować na poziomie partnera lub agenta.

  • Webhook partnera dotyczy każdego prowadzonego przez Ciebie czatu. Jeśli Twoi pracownicy mają podobne zachowania lub masz tylko 1 pracownika, użyj webhooka partnera.
  • Webhooki agentów dotyczą poszczególnych agentów. Jeśli używasz wielu agentów o różnym zachowaniu, możesz dla każdego z nich skonfigurować inny webhook.

Jeśli skonfigurujesz zarówno webhook partnera, jak i webhook agenta, webhook agenta będzie miał pierwszeństwo w przypadku danego agenta, a webhook partnera będzie dotyczył wszystkich agentów, którzy nie mają własnego webhooka.

Konfigurowanie webhooka agenta

Odbierasz wiadomości wysyłane do Twojego agenta na webhook partnera. Jeśli chcesz, aby wiadomości do konkretnego agenta docierały do innego webhooka, skonfiguruj webhook agenta.

  1. Otwórz konsolę programistów Business Communications i zaloguj się na konto Google powiązane z Twoim partnerem RBM.
  2. Kliknij swojego agenta.
  3. Kliknij Integracje.
  4. W przypadku Webhook kliknij Skonfiguruj.
  5. W polu URL punktu końcowego webhooka wpisz adres URL webhooka rozpoczynający się od „https://”.
  6. Zanotuj wartość clientToken. Potrzebujesz go, aby potwierdzić, że otrzymywane wiadomości pochodzą od Google.

  7. Skonfiguruj webhooka tak, aby akceptował żądanie POST z określonym parametrem clientToken, i wysyłaj odpowiedź 200 OK z wartością w postaci zwykłego tekstu parametru secret jako treść odpowiedzi.

    Jeśli np. webhook otrzyma żądanie POST z treścią w polu body

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

    webhook powinien potwierdzić wartość clientToken i, jeśli clientToken jest prawidłowa, zwrócić odpowiedź 200 OK z wartością 1234567890 w treści odpowiedzi:

    // 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. W Konsoli programisty kliknij Zweryfikuj. Gdy RBM potwierdzi Twój webhook, okno zamknie się.

Sprawdzanie wiadomości przychodzących

Ponieważ webhooki mogą otrzymywać wiadomości od dowolnych nadawców, przed przetworzeniem treści wiadomości sprawdź, czy Google wysłał przychodzące wiadomości.

Aby sprawdzić, czy Google wysłało otrzymaną wiadomość:

  1. Wyodrębnij nagłówek X-Goog-Signature wiadomości. Jest to skrót szyfrowania szyfrowania base64 treści komunikatu.
  2. Zdekoduj dane RBM w elementach message.body żądania.
  3. Używając tokena klienta webhooka (który został określony podczas konfigurowania webhooka) jako klucza, utwórz kod HMAC SHA512 z bajtów z dekodowanego za pomocą base64 ładunku wiadomości i zakoduj wynik w formacie base64.
  4. Porównaj hasz X-Goog-Signature z utworzoną przez siebie wartością.
    • Jeśli hasze są zgodne, oznacza to, że wiadomość została wysłana przez Google.

    • Jeśli hasze nie pasują, sprawdź proces haszowania na wiadomości, która działa prawidłowo.

      Jeśli proces szyfrowania działa prawidłowo, a otrzymasz wiadomość, która Twoim zdaniem została wysłana w wyniku oszustwa, skontaktuj się z nami.

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

Obsługa wiadomości

Zwrócenie czegokolwiek innego niż 200 OK przez webhook jest uznawane za niepowodzenie dostawy.

Deweloperzy muszą pamiętać, że wysyłanie wiadomości z dużą częstotliwością spowoduje generowanie powiadomień webhooka z dużą częstotliwością. Muszą też zaprojektować kod tak, aby mógł on odbierać powiadomienia z oczekiwaną częstotliwością. Deweloperzy powinni wziąć pod uwagę sytuacje, które mogą spowodować niepowodzenie odpowiedzi, w tym odpowiedzi 500 z ich kontenera internetowego, przekroczenia limitu czasu lub niepowodzenia na upstream. Oto kilka kwestii, które warto wziąć pod uwagę:

  • Upewnij się, że zabezpieczenia przed atakami typu DDoS są skonfigurowane tak, aby obsługiwać oczekiwaną szybkość powiadomień webhook.
  • Zadbaj o to, aby zasoby takie jak zbiory połączeń baz danych nie kończyły się i nie powodowały przekroczenia limitu czasu ani odpowiedzi 500.

Działanie w przypadku niepowodzenia dostawy

RBM używa mechanizmu wycofywania i powtarzania, gdy otrzyma odpowiedź inną niż 200 OK z wywołania webhooka. RBM wydłuży czas oczekiwania między próbami do maksymalnie 600 sekund. Próby będą podejmowane przez 7 dni, po czym wiadomość zostanie odrzucona.

Konsekwencje korzystania z webhooków na poziomie agenta

RBM kolejkuje wiadomości dla partnera w jednej kolejce. Jeśli partner korzysta z webhooków na poziomie agenta, musi pamiętać, że awaria jednego webhooka wpłynie na dostarczanie do innych webhooków. Webhooki należące do innych agentów będą wywoływane w okresie odroczenia po nieudanej próbie wysłania wiadomości. Jednak gdy nieudane wiadomości będą czekać w kolejce na ponowne wysłanie, ogólne wskaźniki dostarczalności spadną, co wpłynie na innych agentów.

Ważne jest, aby deweloperzy rozumieli ten model i odpowiednio go kodowali – w miarę możliwości należy akceptować wiadomości i umieszczać je w kolejce do przetwarzania, aby zminimalizować możliwość zwrócenia błędu.

Dalsze kroki

Po skonfigurowaniu webhooka Twój agent może odbierać wiadomości z urządzeń testowych. Wyślij wiadomość, aby potwierdzić konfigurację.