Вебхуки

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

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

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

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

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

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

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

  1. Откройте консоль разработчика Business Communications и войдите в систему, используя свою партнерскую учетную запись Google RCS for Business.
  2. Выберите своего агента.
  3. Нажмите «Интеграции» .
  4. Для настройки веб-перехватчика нажмите «Настроить».
  5. В поле «URL-адрес конечной точки веб-перехватчика» введите URL-адрес вашего веб-перехватчика, начинающийся с «https://».
  6. Запишите значение вашего clientToken . Оно необходимо для подтверждения того, что получаемые вами сообщения поступают от Google .

  7. Настройте свой веб-перехватчик так, чтобы он принимал 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);
});

  8. В консоли разработчика нажмите «Проверить» . После того, как RCS for Business проверит ваш веб-перехватчик, диалоговое окно закроется.

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

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

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

  1. Извлеките заголовок X-Goog-Signature сообщения. Это хешированная, закодированная в base64 копия содержимого тела сообщения.
  2. Декодируйте полезную нагрузку RCS for Business с помощью Base-64 в элементе message.body запроса.
  3. Используя токен клиента вашего веб-перехватчика (который вы указали при настройке веб-перехватчика) в качестве ключа, создайте HMAC-скрипт SHA512 из байтов декодированной в base64 полезной нагрузки сообщения и закодируйте результат в base64.
  4. Сравните хеш 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 непосредственно в веб-хуке. Любая ошибка или задержка во время обработки может повлиять на код возврата веб-хука:

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

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

Если ваш веб-хук возвращает что-либо, кроме статуса 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