Вебхуки

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

Партнерские веб-перехватчики и агентские веб-перехватчики

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

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

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

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

  1. Откройте консоль разработчика Business Communications и войдите в свою учетную запись Google партнера RBM.
  2. Нажмите на своего агента.
  3. Нажмите «Интеграции» .
  4. Для Webhook нажмите «Настроить» .
  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. В консоли разработчика нажмите «Подтвердить» . Когда RBM проверит ваш веб-перехватчик, диалоговое окно закроется.

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

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

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

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

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

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

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

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

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