Webhooki

Webhook to określony przez partnera adres URL, na który platforma RBM wysyła 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 przesyłane do aplikacji za pomocą protokołu 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 wydarzenia.

Webhooki partnera i webhooki agenta

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

Webhook partnera ma zastosowanie do każdego agenta, którym zarządzasz. Jeśli Twoi agenci zachowują się podobnie lub masz tylko jednego agenta, użyj webhooka partnera.
Webhooki agenta dotyczą poszczególnych agentów. Jeśli obsługujesz wielu agentów o różnym zachowaniu, możesz ustawić inny webhook dla każdego z nich.

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

Konfigurowanie webhooka agenta

Wiadomości wysłane do Twojego agenta otrzymujesz w webhooku partnera. Jeśli chcesz, aby wiadomości do konkretnego agenta docierały do innego webhooka, ustaw webhooka agenta.

Otwórz Business Communications Developer Console i zaloguj się za pomocą konta Google partnera RBM.
Kliknij agenta.
Kliknij Integrations (Integracje).
Obok pozycji Webhook kliknij Skonfiguruj.
W polu URL punktu końcowego webhooka wpisz adres URL webhooka rozpoczynający się od „https://”.
Zanotuj wartość clientToken. Jest on potrzebny do potwierdzenia, że otrzymywane wiadomości pochodzą od Google.
Skonfiguruj webhooka tak, aby akceptował żądanie POST z określonym parametrem clientToken i wysyłał odpowiedź 200 OK z wartością parametru secret w formie zwykłego tekstu jako treść odpowiedzi.

Jeśli na przykład Twój webhook otrzyma żądanie POST z tą treścią
```
{
  "clientToken":"SJENCPGJESMGUFPY",
  "secret":"1234567890"
}
```
webhook powinien potwierdzić wartość clientToken i jeśli jest ona prawidłowa, zwrócić odpowiedź 200 OK z 1234567890 w treści odpowiedzi:clientToken
```
// 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);
});
```
W Developer Console kliknij Zweryfikuj. Gdy RBM zweryfikuje webhook, okno dialogowe zostanie zamknięte.

Sprawdzanie wiadomości przychodzących

Webhooki mogą otrzymywać wiadomości od dowolnych nadawców, dlatego przed przetworzeniem treści wiadomości musisz sprawdzić, czy zostały one wysłane przez Google.

Aby sprawdzić, czy wiadomość została wysłana przez Google, wykonaj te czynności:

Wyodrębnij nagłówek X-Goog-Signature wiadomości. Jest to zaszyfrowana i zakodowana w base64 kopia treści wiadomości.
Zdekoduj ładunek RBM w formacie Base64 w elemencie message.body żądania.
Używając tokena klienta webhooka (który został określony podczas konfigurowania webhooka) jako klucza, utwórz SHA512 HMAC bajtów ładunku wiadomości zdekodowanego w base64 i zakoduj wynik w base64.
Porównaj hash X-Goog-Signature z utworzonym przez siebie hashem.
- Jeśli hasze są zgodne, oznacza to, że wiadomość została wysłana przez Google.
- Jeśli zahaszowane adresy nie pasują do Twoich wyników, sprawdź proces haszowania na znanym, prawidłowym komunikacie.
  
  Jeśli proces haszowania działa prawidłowo, a otrzymasz wiadomość, która Twoim zdaniem została wysłana w sposób nieuczciwy, 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 z webhooka czegokolwiek innego niż 200 OK jest uznawane za nieudaną dostawę.

Deweloperzy muszą pamiętać, że wysyłanie wiadomości z dużą częstotliwością będzie generować powiadomienia webhook z dużą częstotliwością. Muszą więc zaprojektować kod tak, aby obsługiwał powiadomienia z oczekiwaną częstotliwością. Deweloperzy powinni brać pod uwagę sytuacje, które mogą powodować odpowiedzi o błędach, w tym odpowiedzi 500 z kontenera internetowego, przekroczenia limitu czasu lub błędy w systemie nadrzędnym. Warto wziąć pod uwagę:

Sprawdź, czy ochrona przed atakami DDoS jest skonfigurowana tak, aby obsługiwać oczekiwaną częstotliwość powiadomień webhook.
Sprawdź, czy zasoby, takie jak pule połączeń z bazą danych, nie wyczerpują się i nie powodują przekroczenia limitu czasu lub odpowiedzi 500.

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

Asynchroniczne przetwarzanie webhooków

Ważne jest, aby nie przetwarzać zdarzenia RBM w ramach samego webhooka. Każdy błąd lub opóźnienie podczas przetwarzania może wpłynąć na kod zwrotny webhooka:

Synchroniczne przetwarzanie webhooków

Zachowanie w przypadku niepowodzenia dostawy

RBM używa mechanizmu wycofywania i ponawiania, gdy w odpowiedzi na wywołanie webhooka otrzyma wartość inną niż 200 OK. RBM będzie wydłużać czas oczekiwania między ponownymi próbami do maksymalnie 600 sekund. Ponowne próby będą podejmowane przez 7 dni, po czym wiadomość zostanie odrzucona.

Konsekwencje webhooków na poziomie agenta

RBM kolejkuje wiadomości dla partnera w jednej kolejce. Jeśli partner używa webhooków na poziomie agenta, należy pamiętać, że niepowodzenie jednego webhooka wpłynie na dostarczanie innych webhooków. Webhooki należące do innych agentów będą wywoływane w okresie wycofywania nieudanej wiadomości. Jednak w miarę gromadzenia się nieudanych wiadomości w kolejce do ponownej próby dostarczenia ogólny wskaźnik dostarczania będzie spadać, co wpłynie na innych agentów.

Ważne jest, aby deweloperzy rozumieli ten model i odpowiednio pisali kod – w miarę możliwości akceptowali wiadomości i kolejkowali je do przetworzenia, aby zminimalizować ryzyko zwrócenia błędu.

Dalsze kroki

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

Dalej

Dialogflow