Вебхуки (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 6mo ago