Вебхуки (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":"[phone]", "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": "[phone]"
                    }
                ],
                "4": [ // поле контакт
                    {
                        "contact": "[email protected]"
                    }
                ],
                "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 Бипиума.