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 zaczniesz otrzymywać wiadomości i zdarzenia.

Webhooki partnera i agenta

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

  • Webhook partnera dotyczy każdego sterownika, który obsługujesz. 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

Otrzymasz wiadomości wysłane do Twojego agenta na webhook partnera. Jeśli chcesz, aby wiadomości do konkretnego pracownika obsługi klienta docierały do innego webhooka, skonfiguruj webhook dla pracownika obsługi klienta.

  1. Otwórz Konsolę dewelopera Komunikacji z firmą 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. Zapisz 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łał 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 Google Play 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ść, wykonaj te czynności:

  1. Wyodrębnij nagłówek X-Goog-Signature wiadomości. Jest to skrót szyfrowany w formacie 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 Ty 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ą, i muszą zaprojektować swój kod tak, aby mógł 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 pod kątem obsługi oczekiwanej szybkości powiadomień webhook.
  • Zadbaj o to, aby zasoby takie jak zbiory połączeń baz danych nie kończyły się i nie powodowały limitów czasowych ani odpowiedzi 500.

Deweloperzy powinni zadbać o to, aby przetwarzanie zdarzeń RBM odbywało się asynchronicznie i nie uniemożliwiało webhookowi zwracania wartości 200 OK.

Przetwarzanie żądań webhooka w sposób asynchroniczny

Ważne, aby nie przetwarzać zdarzenia RBM w samym webhooku. Każdy błąd lub opóźnienie podczas przetwarzania może wpłynąć na kod zwracany przez webhook:

Synchroniczne przetwarzanie wywołania webhooka

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 których wiadomość zostanie odrzucona.

Skutki 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 do ponownego wysłania, 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 otrzymywać wiadomości z urządzeń testowych. Wyślij wiadomość, aby potwierdzić konfigurację.

Dalej
Dialogflow