Вебхуки (webhooks)

Процесс создания вебхуков в Бипиуме описан в статье «Вебхуки». Эта статья посвящена обработке вебхуков на стороннем сервере.

События

Виды событий

Бипиум поддерживает 3 вида событий: уведомления, запросы и действия:

Уведомления срабатывают ПОСЛЕ выполнения операции.
Запросы срабатывают ДО выполнения операции и ожидают подтверждения от сторонней системы на совершение действия. Сторонние системы могут разрешить операцию или отклонить её, вернув текст ошибки сотруднику.
Действия срабатывают после изменения поля во время редактирования карточки, до сохранения записи.

Типы событий

record.created — уведомление отправляется после создания записи
record.updated — уведомление отправляется после изменения записи
record.deleted — уведомление отправляется после удаления записи
record.before.created — запрос отправляется перед созданием записи, ожидает одобрения
record.before.updated — запрос отправляется перед изменением записи, ожидает одобрения
record.before.deleted — запрос отправляется перед удалением записи, ожидает одобрения
record.updating — запрос отправляется после изменения поля во время редактирования карточки, не дожидаясь сохранения записи

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

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

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

Вебхук-запросы. Сервер Bpium отправляет запросы подписчикам одновременно и ждет завершения хотя бы одного с ошибкой или завершения всех подписчиков без ошибок. Ответ с ошибкой от первого из подписчиков сервер отправляет сотруднику, не дожидаясь ответа от остальных подписчиков. Ответ может содержать сообщение с информацией об ошибке. Сервер дожидается ответа от каждого подписчика в течение 10 секунд, после чего завершает его с ошибкой (таймаут). Пока сервер Bpium дожидается ответа от сторонних систем, сотрудник также ждёт ответа на завершение операции в системе.

Вебхук-действия. Сервер Bpium отправляет запросы подписчикам одновременно, ждет завершения всех подписчиков, объединяет их результат и отправляет сотруднику. Ответ может содержать сообщение для сотрудника и новые значения для полей записи. Сервер дожидается ответа от каждого подписчика в течение 10 секунд, после чего завершает его с ошибкой (таймаут). Пока сервер Bpium дожидается ответа от сторонних систем, сотрудник может продолжить работу с системой.

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

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

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

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

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

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

Сообщение состоит из 3 частей: информации о вебхуке и событии (hook), изменённые данные (payload) и идентификатор сотрудника (user).

Пример сообщения:

{
  "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

catalogId — идентификатор каталога, в котором создана запись
recordId — идентификатор созданной записи (не отправляется в record.before.created)
values — измененные значения полей в формате метода API на получение записи

События *.updated

catalogId — идентификатор каталога, в котором изменена запись
recordId — идентификатор измененной записи
values — измененные значения полей в формате метода API на получение записи
prevValues — предыдущие значения всех полей в формате метода API на получение записи

События *.deleted

catalogId — идентификатор каталога, в котором удалена запись
recordId — идентификатор удаленной записи

События *.updating

catalogId — идентификатор каталога, в котором изменено поле
recordId — идентификатор редактируемой записи (если запись создана)
values — измененные значения полей в формате метода API на получение записи
allValues — все значения полей в формате метода API на получение записи

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

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

Коды ответов

Бипиум определяет ответ от стороннего сервера по коду HTTP-ответа.

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

HTTP-ответы с кодами 2хх и 3хх, 410. Если Бипиум получит ответ 410, он удалит вебкух.

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

HTTP-ответы с кодами 4хх и 5хх, кроме 410.

Тело ответа

Сторонний сервер отправляет 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"
                    }
                ]
            }
    }

Примечание: Значения полей user, object и file должны быть переданы со всеми дополнительными параметрами. У каждого из этих полей имеется свой формат, как при получении записи.

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

Бипиум подтверждает свою подлинность, подписывая сообщения закрытым ключом алгоритмом 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 Бипиума.

PreviousAPI NextИнтеграция интерфейса

Last updated 1 year ago