Google używa technologii AI do tłumaczenia treści na Twój preferowany język. Tłumaczenia wygenerowane przez AI mogą zawierać błędy.

Webhooki

Webhook to adres URL określony przez partnera, na który platforma RCS dla firm wysyła wiadomości i zdarzenia. Ten adres URL pełni funkcję punktu końcowego, który odbiera żądania HTTPS POST zawierające dane o zdarzeniach. Oznacza to, że dane są bezpiecznie przesyłane do Twojej aplikacji przez HTTPS.

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

Webhooki partnera i webhooki agenta

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

Webhook partnera dotyczy każdego agenta, którego utrzymujesz. 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 masz kilku agentów o różnych zachowaniach, możesz ustawić innego webhooka 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 danego agenta, a webhook partnera będzie stosowany do wszystkich agentów, którzy nie mają własnego webhooka.

Konfigurowanie webhooka agenta

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

Otwórz Konsolę dewelopera RCS dla firm i zaloguj się na konto Google partnera RCS dla firm.
Kliknij swojego agenta.
Kliknij Integrations (Integracje).
W sekcji Webhook kliknij Configure (Skonfiguruj).
1. W polu Webhook endpoint (Punkt końcowy webhooka) wpisz adres URL webhooka zaczynający się od „https://”.
2. W polu Client token (Token klienta) określ wartość clientToken. Jest ona potrzebna do sprawdzenia czy otrzymywane wiadomości pochodzą od Google.
Uwaga: nie można wyświetlić bieżącego tokena klienta ze względów bezpieczeństwa. Aby utworzyć nowy token klienta, wpisz wartość w odpowiednim polu lub kliknij Odśwież , aby wygenerować losową wartość.

Skonfiguruj webhooka tak, aby akceptował żądania POST z ładunkiem JSON zawierającym parametry clientToken i secret.

{
  "clientToken":"YOURCLIENTTOKEN",
  "secret":"YOURSECRET"
}

Aby zweryfikować żądanie, punkt końcowy musi zwrócić kod stanu HTTP 200 OK z wartością parametru secret w postaci nieprzetworzonego ciągu znaków w treści odpowiedzi.

Przykładowa konfiguracja webhooka

Jeśli na przykład webhook otrzyma żądanie POST z taką treścią:

  {
  "clientToken":"YOURCLIENTTOKEN",
  "secret":"YOURSECRET"
  }

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

  // clientToken from Configure
  const myClientToken = "YOURCLIENTTOKEN";

  // Example endpoint
  app.post("/rbm-webhook", (req, res) => {
    // Use the X-Goog-Webhook-Type header to route requests
    const webhookType = req.header('X-Goog-Webhook-Type');

    if (webhookType === 'verification') {
      const msg = req.body;
      if (msg.clientToken === myClientToken) {
          res.status(200).send(msg.secret);
          return;
      }
    }
    res.send(400);
    // Handle other webhook types
  });

W Konsoli dewelopera kliknij Verify (Zweryfikuj). Gdy klikniesz Verify (Zweryfikuj), Google wyśle do webhooka żądanie POST z parametrami clientToken i secret w treści. Gdy RCS dla firm zweryfikuje webhooka, okno dialogowe się zamknie.

Określanie typów żądań

Aby zidentyfikować typ żądania dla wszystkich żądań przychodzących do webhooka, użyj nagłówka X-Goog-Webhook-Type.

Nagłówek może mieć te wartości:

verification: używana w początkowym procesie weryfikacji punktu końcowego.
message_callback: używana w przypadku zdarzeń związanych z wiadomościami, takich jak powiadomienia o pisaniu lub dostarczeniu oraz wiadomości przychodzące od użytkowników.
agent_callback: używana w przypadku zdarzeń administracyjnych dotyczących agenta, takich jak zmiany stanu uruchomienia agenta.

Weryfikowanie wiadomości przychodzących

Webhooki mogą odbierać wiadomości od dowolnego nadawcy, dlatego przed przetworzeniem treści wiadomości należy sprawdzić, czy została ona wysłana przez Google.

Aby sprawdzić, czy otrzymana wiadomość została wysłana przez Google:

Wyodrębnij nagłówek X-Goog-Signature wiadomości. Jest to zaszyfrowana i zakodowana w base64 kopia ładunku treści wiadomości.
Zdekoduj ładunek RCS dla firm w base64 w elemencie message.body żądania.
Używając tokena klienta webhooka (określonego podczas konfigurowania webhooka) jako klucza, utwórz HMAC SHA512 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 hashe są zgodne, oznacza to, że wiadomość została wysłana przez Google.
- Jeśli hashe się nie zgadzają, sprawdź proces haszowania na wiadomości, która na pewno jest prawidłowa.
  
  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
    const headerHash = req.header('X-Goog-Signature');
    const userEventString = Buffer.from(requestBody.message.data, 'base64');
    const hmac = crypto.createHmac('sha512', myClientToken);
    const genHash = hmac.update(userEventString).digest('base64');

    if (headerHash === genHash) {
      const userEvent = JSON.parse(userEventString);
      const webhookType = req.header('X-Goog-Webhook-Type');

      // Route based on the header type
      if (webhookType === 'message_callback') {
        handleMessage(userEvent);
      } else if (webhookType === 'agent_callback') {
        handleAgentEvent(userEvent);
      }
    } else {
      console.log('Hash mismatch - ignoring message');
      res.sendStatus(401);
      return;
    }
  }

  res.sendStatus(200);

Obsługa wiadomości

Zwrócenie z webhooka czegokolwiek innego niż 200 OK jest uznawane za błąd dostarczenia.

Deweloperzy muszą pamiętać, że wysyłanie wiadomości z dużą częstotliwością będzie generować powiadomienia webhooka z dużą częstotliwością, i muszą zaprojektować kod tak, aby obsługiwał powiadomienia z oczekiwaną częstotliwością. Deweloperzy muszą wziąć pod uwagę sytuacje, które mogą powodować odpowiedzi o błędach, w tym odpowiedzi 500 z kontenera internetowego, przekroczenia limitu czasu lub błędy upstream. Oto kilka kwestii, które należy wziąć pod uwagę:

Sprawdź, czy zabezpieczenia przed atakami DDoS są skonfigurowane tak, aby obsługiwać oczekiwaną częstotliwość powiadomień webhooka.
Upewnij się, że zasoby, takie jak pule połączeń z bazą danych, nie wyczerpują się i nie powodują przekroczenia limitu czasu ani odpowiedzi 500.

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

Asynchroniczne przetwarzanie webhooków

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

Synchroniczne przetwarzanie webhooków

Zachowanie w przypadku błędu dostarczenia

Jeśli webhook zwróci kod stanu inny niż 200 OK, platforma RCS dla firm użyje mechanizmu wycofywania i ponawiania, aby ponownie dostarczyć dane. Oznacza to, że system stopniowo zwiększa opóźnienie między kolejnymi próbami dostarczenia, aż osiągnie maksymalną częstotliwość ponawiania wynoszącą 1 próbę co 10 minut w przypadku każdej oczekującej wiadomości. Cykl ponawiania trwa 7 dni, po czym wiadomość jest trwale usuwana.

Konsekwencje korzystania z webhooków na poziomie agenta

RCS dla firm umieszcza wiadomości dla partnera w jednej kolejce. Wszyscy agenci na jednym koncie partnera korzystają z jednej kolejki. Z tego powodu błąd w jednym webhooku może zablokować całą kolejkę, uniemożliwiając dotarcie do partnera zdarzeń użytkownika dotyczących wszystkich agentów.

Kilka niepotwierdzonych wiadomości może spowodować gwałtowny wzrost liczby zdarzeń ponawiania. Jeśli na przykład agent nie potwierdzi 1600 potwierdzeń dostarczenia, a częstotliwość ponawiania osiągnie limit 10 minut, może to wygenerować około 230 tys. potencjalnych błędów dziennie:

1600 wiadomości × 6 prób ponowienia na godzinę × 24 godziny na dobę = około 230 tys. błędów dziennie

Taka liczba prób ponowienia może zablokować współdzieloną kolejkę Pub/Sub i spowodować znaczne opóźnienia w odbieraniu zdarzeń użytkownika dotyczących wszystkich kampanii partnera.

Sprawdzone metody

Aby zapewnić niezawodność ruchu produkcyjnego i uniknąć blokowania kolejki, stosuj te sprawdzone metody:

Natychmiastowe zwracanie kodu 200 OK: webhook powinien odebrać wiadomość, zapisać ją w kolejce lokalnej i zwrócić odpowiedź 200 OK w ciągu 5 sekund.
Oddzielenie przetwarzania: do przetwarzania logiki wiadomości z kolejki lokalnej używaj osobnych procesów działających w tle.
Monitorowanie agentów testowych: traktuj agentów deweloperskich jak agentów produkcyjnych, ponieważ w przypadku awarii mogą oni również zablokować współdzieloną kolejkę partnera.
Osobne konta do testowania: najlepiej używaj jednego konta dewelopera do agentów produkcyjnych i osobnego konta dewelopera do agentów testowych.
Weryfikowanie ruchu Google: używaj odwrotnego DNS lub nagłówka X-Goog-Signature zamiast stałej listy dozwolonych adresów IP, ponieważ Google używa dynamicznych adresów IP anycast. Więcej informacji o ręcznej weryfikacji i identyfikowaniu zakresów adresów IP Google znajdziesz w dokumentacji Weryfikowanie żądań Google, a w szczególności w plikach JSON dotyczących modułów pobierania uruchamianych przez użytkownika i modułów pobierania uruchamianych przez użytkownika Google.

Dalsze kroki

Po skonfigurowaniu webhooka agent może odbierać wiadomości z urządzeń testowych. Wyślij wiadomość aby sprawdzić poprawność konfiguracji.

Dalej

Dialogflow