Вебхуки (webhooks)

Эта статья описывает обработку вебхуков на стороне внешнего сервера — форматы запросов и ответов.

Настройка вебхуков в Бипиуме описана в статье «Вебхуки».

События

Виды событий

Бипиум поддерживает 3 вида событий:

Типы событий

Принцип работы

Когда наступает одно из событий, Бипиум выбирает подходящие подписки и рассылает сообщения сторонним системам. Если подходящих подписок несколько, то события отправляются параллельно на все адреса.

Вебхук-уведомления

Сервер Bpium отправляет запросы подписчикам одновременно и не ждет завершения их работы. Работа сотрудника в системе не блокируется.

Вебхук-запросы

Сервер Bpium отправляет запросы подписчикам одновременно и ждет завершения хотя бы одного с ошибкой или завершения всех подписчиков без ошибок.

• Таймаут ожидания — 10 секунд.

• Ответ с ошибкой от первого подписчика сразу возвращается сотруднику.

Вебхук-действия

Сервер Bpium:

1. Отправляет запросы подписчикам.

2. Ждет завершения всех подписчиков.

3. Объединяет результаты.

4. Возвращает новые значения полей сотруднику.

Очередь отправки

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

Порядковый номер сообщения

Бипиум отсчитывает сколько раз сработал каждый вебхук и отправляет это число (sequenceId) в сообщении. Этот счетчик помогает отследить были ли пропущены события принимающей стороной

Формат запроса

Запрос — HTTP-запрос сервера Bpium к сторонней системе с информацией о событии. Запрос состоит из:

Пример запроса

{
  "timestamp" : "1459500623", // время события
  "hook" : {
    "id" : "2", // номер вебхука в системе
    "event" : "record.before.updated", // тип события
    "sequenceId" : 84 // порядковый номер сообщения
   },
   "payload" : { 
     "catalogId" : "5", // каталог с изменениям
     "recordId" : "199", // запись с изменениям
     "values" : { // список измененных полей и значений в формате API Бипиума
       "2" : "Текст",
       "3" : null,
       "4" : ["1"],
       "5" : [ {"id":"1", "title":"admin"} ],
       "6" : "2016-04-01T08:49:15.920Z",
       "9" : [ {"contact":"+7-987-654-32-10", "comment":"Сотовый"} ]
     },
     "prevValues" : {
       // предыдущие значения записи
     }
  },
  "user" : { "id" : "1" } // идентификатор сотрудника
}

Измененные данные (payload)

События *.created

События *.updated

События *.deleted

События *.updating

Формат ответа

Ответ — HTTP-ответ сторонней системе на запрос от сервера Bpium.

Коды ответов

Успешные коды ответов

Неуспешные коды ответов

Тело ответа

Сторонний сервер отправляет HTTP-ответ в формате JSON и должен указать заголовок Content-type: 'application/json; charset=utf-8' .

Вебхук-уведомления

Сервер Bpium не ожидает никакого ответа от стороннего сервера.

Вебхук-запросы

HTTP-ответ может включать сообщение (message) , которое будет показано сотруднику, если сторонний сервер ответит неуспешным кодом на вебхук-запрос событие. Сообщение для сотрудника может быть указано в виде строки или объекта с полями title и text.

Пример

{
    "message": { // опционально, string или object{title, text} 
        "title": "Информация",
        "text": "Отказано в доступе!"
    }
}

Вебхук-действия

HTTP-ответа может включать сообщение (message) , которое будет показано сотруднику, и новые значения полей (values) для автоматической подстановки в карточку записи на экране сотрудника. Сообщение для сотрудника может быть указано в виде строки или объекта с полями title и text.

Пример

{
    "message": { // опционально, string или object{title, text} 
        "title": "Информация",
        "text": "Сотрудник найден"
     },
     "values": { // опционально
         "2": "Steve", // текстовое поле
         "3": [ // поле контакт
             {
                 "contact": "+78000000000"
             }
         ],
         "4": [ // поле контакт
             {
                 "contact": "Steve@gmail.com"
             }
         ],
         "5": [ // поле связанный объект
             {
                 "recordId": "5",
                 "catalogId": "65",
                 "sectionId": "18",
                 "recordTitle": "Отдел продаж",
                 "catalogIcon": "content-11"
             }
         ]
     }
}

Безопасность

Бипиум подтверждает свою подлинность, подписывая сообщения закрытым ключом алгоритмом HMAC-MD5. Закрытый ключ задаётся в настройках вебхука.

Подпись передается в HTTP-заголовке X-Hook-Signature закодированная алгоритмом Base64.

Пример PHP

$signature = base64_encode(
    hash_hmac('md5', $body, $secretKey, true)
);

Пример Node.js

var http = require('http');
var textBody = require("body");
var crypto = require('crypto');

http.createServer(function (req, res, opts) {
  textBody(req, function (err, body)  {
      var hmac = crypto.createHmac( 'md5', secretKey );
          hmac.setEncoding('base64');
          hmac.write( body );
          hmac.end();
      signature = hmac.read();

      // ...

  });
}).listen(80);

API

Список вебхуков хранится в каталоге «Вебхуки» в отделе «Управление». Это значит, что для получения вебхуков и создания новых можно использовать стандартные методы API Бипиума.