Вебхуки (webhooks)

Last updated 24 days ago

Процесс создания вебхуков в Бипиуме описан в статье «События (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 Бипиума.