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

Вебхуки

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

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

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

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

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

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

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

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

Откройте консоль разработчика Business Communications и войдите в систему, используя свою партнерскую учетную запись Google RBM.
Выберите своего агента.
Нажмите «Интеграции» .
Для настройки веб-перехватчика нажмите «Настроить».
В поле «URL-адрес конечной точки веб-перехватчика» введите URL-адрес вашего веб-перехватчика, начинающийся с «https://».
Запишите значение вашего clientToken . Оно необходимо для подтверждения того, что получаемые вами сообщения поступают от Google .
Настройте свой веб-перехватчик так, чтобы он принимал POST запрос с указанным параметром clientToken и отправлял ответ 200 OK , содержащий в теле ответа текстовое значение параметра secret .
Например, если ваш веб-хук получает POST запрос со следующим содержимым тела запроса
```
{
  "clientToken":"SJENCPGJESMGUFPY",
  "secret":"1234567890"
}
```
В этом случае ваш веб-хук должен подтвердить значение clientToken и, если clientToken верен, вернуть ответ 200 OK с телом ответа 1234567890 :
```
// 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);
});
```
В консоли разработчика нажмите «Проверить» . После того, как RBM проверит ваш веб-перехватчик, диалоговое окно закроется.

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

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

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

Извлеките заголовок X-Goog-Signature сообщения. Это хешированная, закодированная в base64 копия содержимого тела сообщения.
Декодируйте полезную нагрузку RBM в элементе message.body запроса с помощью Base-64.
Используя токен клиента вашего веб-перехватчика (который вы указали при настройке веб-перехватчика) в качестве ключа, создайте 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
    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);

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

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

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

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

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

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

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

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

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

RBM использует механизм задержки и повторных попыток при получении ответа, отличного от 200 OK от вызова веб-перехватчика. RBM увеличивает время ожидания между повторными попытками до максимума в 600 секунд. Повторные попытки будут продолжаться в течение 7 дней , после чего сообщение будет отброшено.

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

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

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

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

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

Dialogflow