Вебхуки (webhooks)
Процесс создания вебхуков в Бипиуме описан в статье «События (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).
Пример сообщения:
1
{
2
"timestamp" : "1459500623", // время события
3
"hook" : {
4
"id" : "2", // номер вебхука в системе
5
"event" : "record.before.updated", // тип события
6
"sequenceId" : 84 // порядковый номер сообщения
7
},
8
"payload" : {
9
"catalogId" : "5", // каталог с изменениям
10
"recordId" : "199", // запись с изменениям
11
"values" : { // список измененных полей и значений в формате API Бипиума
12
"2" : "Текст",
13
"3" : null,
14
"4" : ["1"],
15
"5" : [ {"id":"1", "title":"admin"} ],
16
"6" : "2016-04-01T08:49:15.920Z",
17
"9" : [ {"contact":"+7-987-654-32-10", "comment":"Сотовый"} ]
18
},
19
"prevValues" : {
20
// предыдущие значения записи
21
}
22
},
23
"user" : { "id" : "1" } // идентификатор сотрудника
24
}
Copied!

Измененные данные (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.
Формат ответа от стороннего сервера:
1
{
2
"message": { // опционально, string или object{title, text}
3
"title": "Информация",
4
"text": "Отказано в доступе!"
5
}
6
}
Copied!

Вебхук-действия

HTTP-ответа может включать сообщение (message) , которое будет показано сотруднику, и новые значения полей (values) для автоматической подстановки в карточку записи на экране сотрудника. Сообщение для сотрудника может быть указано в виде строки или объекта с полями title и text.
Формат ответа от стороннего сервера:
1
{
2
"message": { // опционально, string или object{title, text}
3
"title": "Информация",
4
"text": "Сотрудник найден"
5
},
6
"values": { // опционально
7
"2": "Steve", // текстовое поле
8
"3": [ // поле контакт
9
{
10
"contact": "+78000000000"
11
}
12
],
13
"4": [ // поле контакт
14
{
15
"contact": "[email protected]"
16
}
17
],
18
"5": [ // поле связанный объект
19
{
20
"recordId": "5",
21
"catalogId": "65",
22
"sectionId": "18",
23
"recordTitle": "Отдел продаж",
24
"catalogIcon": "content-11"
25
}
26
]
27
}
28
}
Copied!
Примечание: Значения полей user, object и file должны быть переданы со всеми дополнительными параметрами. У каждого из этих полей имеется свой формат, как при получении записи.

Безопасность

Бипиум подтверждает свою подлинность, подписывая сообщения закрытым ключом алгоритмом HMAC-MD5. Закрытый ключ задаётся в настройках вебхука.
Подпись передается в HTTP-заголовке X-Hook-Signature закодированная алгоритмом Base64.
Пример на PHP
1
$signature = base64_encode( hash_hmac( 'md5', $body, $secretKey, true ) );
Copied!
Пример на Node.js
1
var http = require('http');
2
var textBody = require("body");
3
var crypto = require('crypto');
4
5
http.createServer(function (req, res, opts) {
6
textBody(req, function (err, body) {
7
var hmac = crypto.createHmac( 'md5', secretKey );
8
hmac.setEncoding('base64');
9
hmac.write( body );
10
hmac.end();
11
signature = hmac.read();
12
13
// ...
14
15
});
16
}).listen(80);
Copied!

API

Список вебхуков хранится в каталоге «Вебхуки» в отделе «Управление». Это значит, что для получения вебхуков и создания новых можно использовать стандартные методы API Бипиума.
Last modified 3yr ago