Вебхуки (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" } // идентификатор сотрудника
}
catalogId— идентификатор каталога, в котором создана записьrecordId— идентификатор созданной записи (не отправляется вrecord.before.created)
catalogId— идентификатор каталога, в котором изменена записьrecordId— идентификатор измененной записи
catalogId— идентификатор каталога, в котором удалена записьrecordId— идентификатор удаленной записи
catalogId— идентификатор каталога, в котором изменено полеrecordId— идентификатор редактируемой записи (если запись создана)
Ответ — 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 Бипиума.
Last modified 2mo ago