Бипуим: Документация
8-800-505-24-05Сайт Бипиум
  • 😎Отвечаем на ваши вопросы
  • 🎂Версии и обновления
  • ❗Обновление до версии 2.0
  • Документация
    • 🆕С чего начать
      • Регистрация и вход
      • Создаем каталоги и записи
      • Формируем отчёты
      • Настраиваем правовую политику
      • Применяем автоматизации
    • ⚙️Конструктор данных
      • Отделы
      • Каталоги
        • Редактирование структуры
        • Настройка отображения
        • Поиск и фильтрация
        • Импорт записей
          • 📗Импорт из Excel
        • Экспорт записей
        • Активность
      • Системные каталоги
        • Сотрудники
        • События
        • Внешние запросы
        • Сценарии
        • Процессы
        • Доступ к сервисам
        • Вебхуки
      • Виды
      • Записи
    • 📊Отчеты
      • Графики
    • 🔑Права
      • Правила
      • Привилегии
      • Правовые группы
      • Правовые виды
      • Права на поля
      • Комбинация прав
    • 🤖Автоматизации
      • События
        • Изменение данных
        • Внешние запросы
      • Сценарии
        • Компоненты
          • Начало процесса
          • Конец процесса
          • Таймер
          • Ошибка
          • Шлюз «ИЛИ» (условное ветвление)
          • Шлюз «И» (распараллеливание)
          • Получить запись
          • Найти записи
          • Изменить запись
          • Создать запись
          • Удалить запись
          • Структура каталога
          • Загрузить файл
          • Сгенерировать документ
          • Назначение переменных
          • Код (Javascript)
          • Веб-запрос
          • SQL-запрос
          • Конвертер
          • Парсер
          • Запуск процесса
          • Получение почты
          • Отправка почты
          • Соединяющая линия
          • Отправить сообщение
        • Переменные
        • Выражения
        • Входные и выходные параметры компонентов
        • Примеры настройки
          • Условие
          • Цикл
      • Ограничения
  • Лицензии
    • 🌐Тип лицензирования
  • Примеры
    • 🔑Права доступа к данным
    • 🤖Автоматизации
      • Выгрузка файлов на Яндекс Диск
      • Отправка на больничный
      • Автоматизация оплаты счетов
      • Создание наименований записей
      • Расчет скидок для клиентов
      • Запрет на создание дубликатов в каталоге
      • Автозаполнение данных по ИНН
      • Переброс данных между связанными каталогами
      • Очередь сценариев
      • Отслеживание заявок с сайта помощью UTM-меток
      • Просрочка задач по дедлайну
      • Реализация механизма согласования записей
      • Массовое изменение записей
      • Создание каталога для рассылки почты
      • Перенос данных между системами Бипиума
      • Импорт данных из Excel
      • Генерация счет-фактуры
      • Генерация excel-отчетов
      • Планировщик задач
      • Импорт банковских выписок
      • Производственный календарь
      • Складской учет
  • Интеграции
    • 🥂Методы интеграции
      • Интеграция данных
        • API
        • Вебхуки (webhooks)
      • Интеграция интерфейса
        • Веб-формы
        • Веб-расширения
      • Примеры интеграций
        • Тильда
          • Прием данных с формы Tilda
          • Интеграция веб-интерфейса в Tilda
        • Интеграция с сервисом «DaData»
        • Интеграция c «Единой информационной системой в сфере закупок»
        • Мессенджеры
          • Интеграция с Telegram-ботом
        • Почтовые сервисы
          • UniSender
          • MailChimp
        • Сервисы Google
          • Google Calendar
        • Телефония
          • Oktell
            • Панель телефонии Oktell
            • Компонент Bpium в Oktell
        • 1C
    • 🔌API
      • Данные
        • Каталоги (Catalogs)
        • Записи (Records)
        • Связи (Relations)
        • Истории (Histories)
        • Файлы (Files)
        • Отделы (Sections)
        • Виды (Views)
        • Сообщения (Messages)
      • Агрегация
        • Разложения (Values)
        • Сводка (Totals)
      • Отчеты
        • Дашборды (Boards)
        • Графики (Widgets)
      • Поисковые выборки
        • Доступные связи (AvailableRecords)
        • Доступные условия фильтра (AvailableFilterRecords)
        • Сотрудники (Users)
        • Контакты (Contacts)
      • Права (Rights)
      • Профиль (Profile/me)
  • Установка на сервер
    • 🧱Архитектура
      • Варианты разворачивания
    • 🖥️Требования
    • 📂Установка как служба
    • 🛳️Установка через Docker
    • 🎛️Мультидоменная среда
    • 🆘Материалы
      • TLS/SSL Сертификат
      • Параметры config.env
        • Для Bpium
        • Для Bpium S3
        • Для Bpium BPM
      • Запуск
      • Обсуживание
        • Активация
        • Обновление
        • Бэкап и восстановление базы
        • Брендирование (Whitelabel)
        • Удаление
      • Перенос базы из облака
      • Возможные проблемы в ходе установки и работы
  • Обучение
    • Базовый курс
      • Урок 1. Отделы
      • Урок 2. Каталоги с данными
      • Урок 3. Карточки записей
      • Урок 4. Связи между данными
      • Урок 5. Фильтры и виды
      • Урок 6. Приглашение сотрудников
      • Урок 7. Права доступа к данным
      • Урок 8. Графические отчеты
      • Урок 9. Бизнес-процессы
      • Урок 10. Интеграции
    • Технический курс
      • Урок 1. Принцип работы автоматизаций
      • Урок 2. Первая автоматизация изнутри
      • Урок 3. Валидация данных
      • Урок 4. Простые вычисления
      • Урок 5. Расчет суммы заказа
      • Урок 6. Генерация счетов/документов
      • Урок 7. Рассылка почтовых сообщений
      • Урок 8. Прием внешних данных
      • Урок 9. Отправка данных на сторонние сервисы
    • Паттерны проектирования ИС
      • Унификация
      • Упорядоченность
      • Разделение
      • Актуализация
      • Вынос параметров
      • Выделение позиций
      • Слияние
      • Дублирование
      • Типизация
      • Информирование
Powered by GitBook
On this page
  • События
  • Виды событий
  • Типы событий
  • Принцип работы
  • Очередь отправки
  • Порядковый номер сообщения
  • Формат запроса
  • Измененные данные (payload)
  • Формат ответа
  • Коды ответов
  • Тело ответа
  • Безопасность
  • API
  1. Интеграции
  2. Методы интеграции
  3. Интеграция данных

Вебхуки (webhooks)

PreviousAPINextИнтеграция интерфейса

Last updated 2 years ago

Процесс создания вебхуков в Бипиуме описан в статье «». Эта статья посвящена обработке вебхуков на стороннем сервере.

События

Виды событий

Бипиум поддерживает 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)

События *.updated

  • catalogId — идентификатор каталога, в котором изменена запись

  • recordId — идентификатор измененной записи

События *.deleted

  • catalogId — идентификатор каталога, в котором удалена запись

  • recordId — идентификатор удаленной записи

События *.updating

  • 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": "Steve@gmail.com"
                    }
                ],
                "5": [ // поле связанный объект
                    {
                        "recordId": "5",
                        "catalogId": "65",
                        "sectionId": "18",
                        "recordTitle": "Отдел продаж",
                        "catalogIcon": "content-11"
                    }
                ]
            }
    }

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

Подпись передается в 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

values — измененные значения полей в формате метода API на

values — измененные значения полей в формате метода API на

prevValues — предыдущие значения всех полей в формате метода API на

values — измененные значения полей в формате метода API на

allValues — все значения полей в формате метода API на

Примечание: Значения полей user, object и file должны быть переданы со всеми дополнительными параметрами. У каждого из этих полей имеется свой формат, как при .

Бипиум подтверждает свою подлинность, подписывая сообщения закрытым ключом алгоритмом . Закрытый ключ задаётся в настройках вебхука.

Список вебхуков хранится в каталоге «» в отделе «Управление». Это значит, что для получения вебхуков и создания новых можно использовать стандартные методы .

🥂
Вебхуки
получение записи
получение записи
получение записи
получение записи
получение записи
получении записи
HMAC-MD5
Вебхуки
API Бипиума