Вебхуки (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": "[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 Бипиума.
Last updated