Вебхуки (webhooks)
Last updated
Last updated
Процесс создания вебхуков в Бипиуме описан в статье «». Эта статья посвящена обработке вебхуков на стороннем сервере.
Бипиум поддерживает 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
).
Пример сообщения:
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.
Формат ответа от стороннего сервера:
HTTP-ответа может включать сообщение (message
) , которое будет показано сотруднику, и новые значения полей (values
) для автоматической подстановки в карточку записи на экране сотрудника. Сообщение для сотрудника может быть указано в виде строки или объекта с полями title и text.
Формат ответа от стороннего сервера:
Подпись передается в HTTP-заголовке X-Hook-Signature
закодированная алгоритмом Base64.
Пример на PHP
Пример на Node.js
values
— измененные значения полей в формате метода API на
values
— измененные значения полей в формате метода API на
prevValues
— предыдущие значения всех полей в формате метода API на
values
— измененные значения полей в формате метода API на
allValues
— все значения полей в формате метода API на
Примечание: Значения полей user
, object
и file
должны быть переданы со всеми дополнительными параметрами. У каждого из этих полей имеется свой формат, как при .
Бипиум подтверждает свою подлинность, подписывая сообщения закрытым ключом алгоритмом . Закрытый ключ задаётся в настройках вебхука.
Список вебхуков хранится в каталоге «» в отделе «Управление». Это значит, что для получения вебхуков и создания новых можно использовать стандартные методы .