Эта страница переведена с помощью Cloud Translation API.

Вебхуки

Веб-хук — это указанный партнёром URL-адрес, куда платформа RCS for Business отправляет сообщения и события . Этот URL-адрес выступает в качестве конечной точки, принимающей HTTPS POST-запросы, содержащие данные о событиях. Это означает, что данные безопасно передаются в ваше приложение по протоколу HTTPS.

URL веб-перехватчика может выглядеть примерно так: https://[your company name].com/api/rbm-events . После настройки веб-перехватчика вы сможете начать получать сообщения и события.

Веб-хуки партнеров и веб-хуки агентов

Вы можете настроить веб-перехватчик либо на уровне партнера, либо на уровне агента.

Ваш партнерский веб-перехватчик применяется ко всем вашим агентам. Если ваши агенты ведут себя схожим образом или если у вас только один агент, используйте партнерский веб-перехватчик .
Веб-хуки агентов применяются к отдельным агентам. Если вы используете несколько агентов с различным поведением, вы можете установить отдельный веб-хук для каждого агента .

Если вы настроили как веб-перехватчик партнера, так и веб-перехватчик агента, то веб-перехватчик агента будет иметь приоритет для своего конкретного агента, в то время как веб-перехватчик партнера будет применяться ко всем агентам, у которых нет собственного веб-перехватчика.

Настройте веб-перехватчик агента.

Сообщения, отправленные вашему агенту, поступают через веб-перехватчик вашего партнера. Если вы хотите, чтобы сообщения для конкретного агента поступали через другой веб-перехватчик, настройте веб-перехватчик для агента.

Откройте консоль разработчика RCS for Business и войдите в систему, используя свою партнерскую учетную запись Google RCS for Business.
Выберите своего агента.
Нажмите «Интеграции» .
В разделе «Веб-перехватчик» нажмите «Настроить» .
1. В поле «Конечная точка веб-перехватчика» введите URL-адрес вашего веб-перехватчика, начинающийся с «https://».
2. В поле «Токен клиента» укажите значение clientToken . Оно необходимо для подтверждения того, что получаемые вами сообщения поступают от Google.
Примечание: Ваш текущий клиентский токен не может быть отображен по соображениям безопасности. Чтобы создать новый клиентский токен, введите значение в соответствующее поле или нажмите кнопку », чтобы сгенерировать случайное значение.
Настройте свой веб-перехватчик для приема POST запросов с JSON-данными, включающими параметры clientToken и secret .
```
{
  "clientToken":"YOURCLIENTTOKEN",
  "secret":"YOURSECRET"
}
```
Для проверки запроса ваша конечная точка должна возвращать код состояния HTTP 200 OK а в теле ответа должно содержаться строковое значение параметра secret .
Пример конфигурации веб-перехватчика
Например, если ваш веб-хук получает POST запрос со следующим содержимым тела:
```
  {
  "clientToken":"YOURCLIENTTOKEN",
  "secret":"YOURSECRET"
  }
  
```
Затем ваш веб-хук должен подтвердить значение clientToken и, если clientToken верен, вернуть ответ 200 OK с YOURSECRET в качестве тела ответа:
```
  // 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
  });
  
```
В консоли разработчика нажмите «Проверить» . После нажатия кнопки «Проверить» Google отправит POST запрос на ваш веб-перехватчик, передав в теле запроса clientToken и secret в качестве параметров. После проверки вашего веб-перехватчика RCS for Business диалоговое окно закроется.

Определите типы запросов

Для определения типа запроса для всех запросов, поступающих на ваш веб-хук, используйте заголовок X-Goog-Webhook-Type .

Заголовок может содержать следующие значения:

verification : Используется для первоначальной проверки конечной точки.
message_callback : Используется для событий, связанных с сообщениями, таких как ввод текста, уведомления о доставке и входящие сообщения от пользователей.
agent_callback : Используется для административных событий, специфичных для агента, таких как изменение состояния запуска агента.

Проверка входящих сообщений

Поскольку веб-хуки могут получать сообщения от любого отправителя, перед обработкой содержимого сообщения следует убедиться, что входящие сообщения были отправлены Google.

Чтобы убедиться, что Google отправил полученное вами сообщение, выполните следующие действия:

Извлеките заголовок X-Goog-Signature сообщения. Это хешированная, закодированная в base64 копия содержимого тела сообщения.
Декодируйте полезную нагрузку RCS for Business с помощью Base-64 в элементе message.body запроса.
Используя токен клиента вашего веб-перехватчика (который вы указали при настройке веб-перехватчика) в качестве ключа, создайте HMAC-скрипт SHA512 из байтов декодированной в base64 полезной нагрузки сообщения и закодируйте результат в base64.
Сравните хеш X-Goog-Signature с хешем, который вы создали.
- Если хеши совпадают, значит, вы подтвердили, что сообщение было отправлено Google.
- Если хеши не совпадают, проверьте процесс хеширования на заведомо корректном сообщении.
  Если процесс хеширования работает корректно, но вы получаете сообщение, которое, по вашему мнению, было отправлено вам мошенническим путем, свяжитесь с нами .

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

Обработка сообщений

Возвращение веб-хука с кодом, отличным от 200 OK , считается ошибкой доставки.

Разработчикам следует помнить, что отправка сообщений с высокой частотой приведет к генерации большого количества уведомлений через веб-перехватчики, и поэтому необходимо проектировать свой код таким образом, чтобы обрабатывать уведомления с ожидаемой частотой. Разработчикам важно учитывать ситуации, которые могут привести к ошибкам, включая ответы 500 от веб-контейнера, тайм-ауты или сбои в вышестоящих системах. Следует учитывать следующие моменты:

Убедитесь, что ваши средства защиты от DDoS-атак настроены на обработку ожидаемого количества уведомлений от веб-перехватчиков.
Убедитесь, что ресурсы, такие как пулы соединений с базой данных, не исчерпываются и не приводят к таймаутам или ответам с кодом 500 .

Разработчикам следует проектировать свои системы таким образом, чтобы обработка событий RBM происходила асинхронно и не препятствовала возврату веб-перехватчиком кода 200 OK .

Асинхронная обработка веб-перехватчиков

Важно не обрабатывать событие RBM непосредственно в веб-хуке. Любая ошибка или задержка во время обработки может повлиять на код возврата веб-хука:

Синхронная обработка веб-хуков

Поведение при сбое доставки

Если ваш веб-хук возвращает что-либо, кроме статуса 200 OK , платформа RCS for Business использует механизм задержки и повторной попытки для повторной доставки данных. Это означает, что система постепенно увеличивает задержку между каждой попыткой доставки, в конечном итоге достигая максимальной частоты одной повторной попытки каждые 10 минут для каждого ожидающего сообщения. Цикл повторных попыток продолжается в течение семи дней, после чего сообщение удаляется навсегда.

Последствия использования веб-хуков на уровне агентов.

RCS for Business помещает сообщения для партнера в одну очередь. Все агенты, работающие под одной учетной записью партнера, используют одну очередь. Из-за этого сбой в одном веб-хуке может заблокировать всю очередь, препятствуя доставке событий пользователей для всех агентов партнеру.

Несколько неподтвержденных сообщений могут вызвать резкий скачок числа повторных попыток. Например, если агент не подтвердит 1600 уведомлений о доставке, и частота повторных попыток достигнет 10-минутного лимита, это может привести к возникновению примерно 230 000 потенциальных ошибок в день:

1600 сообщений × 6 повторных попыток в час × 24 часа в сутки = приблизительно 230 000 ошибок в день

Такое количество повторных попыток может заблокировать общую очередь Pub/Sub и вызвать значительные задержки в получении событий пользователей для всех кампаний партнера.

Передовые методы

Для обеспечения надежности производственного трафика и предотвращения блокировок очередей следуйте этим рекомендациям:

Немедленно вернуть код 200 OK : веб-хук должен получить сообщение, сохранить его в локальной очереди и вернуть ответ 200 OK менее чем за пять секунд.
Разделение обработки : Используйте отдельные фоновые процессы для обработки логики сообщений из локальной очереди.
Отслеживайте работу тестовых агентов : рассматривайте агенты разработки как агенты производственной среды, поскольку они также могут блокировать общую очередь партнеров в случае сбоя.
Выделенные учетные записи для тестирования : Желательно использовать одну учетную запись разработчика для агентов, работающих в производственной среде, и выделенную учетную запись разработчика для агентов тестирования.
Проверка трафика Google : используйте обратное DNS-запрос или заголовок X-Goog-Signature вместо фиксированного списка разрешенных IP-адресов, поскольку Google использует динамические IP-адреса anycast. Для получения дополнительной информации о ручной проверке и определении диапазонов IP-адресов Google см. документацию по проверке запросов Google , а именно файлы JSON для запросов, инициируемых пользователем , и запросов Google, инициируемых пользователем .

Следующие шаги

После настройки веб-хука ваш агент сможет получать сообщения с тестовых устройств . Отправьте сообщение для проверки правильности настройки.

Dialogflow