Узел Вебхук

Технический обзор и возможности

Узел Вебхук позволяет в реальном времени запускать определённые действия во внешних системах. Он отправляет HTTP POST-запросы на указанные конечные точки при получении данных от подключённых узлов. Затем он формирует пользовательские JSON-пакеты как со статическими, так и с динамическими атрибутами и выполняет API-вызовы к сторонним сервисам.

Этот узел расширяет возможности IoT Logic за пределы обработки и передачи данных, обеспечивая прямую интеграцию с платформами обмена сообщениями, системами ERM и CRM, а также пользовательскими приложениями для запуска автоматизированных действий на основе конфигурации вашего потока.

Узлы Вебхук настраиваются отдельно для каждого потока в интерфейсе платформы ГМ Телематика. Узлы Вебхук служат конечными точками в потоке и для работы требуют как минимум одно входящее соединение. Они не могут передавать данные в последующие узлы.

Как работают узлы Вебхук

Когда данные поступают в узел Вебхук через входящее соединение, он немедленно выполняет HTTP POST-запрос на настроенную конечную точку. Узел:

• Собирает текущие значения всех атрибутов из подключённых вышестоящих узлов

• Заменяет ссылки на динамические атрибуты (например, {{speed}}) фактическими значениями из входящего сообщения

• Формирует полный JSON-пакет, сохраняя заданную вами структуру

• Отправляет HTTP POST-запрос с указанными заголовками на целевую конечную точку

• Продолжает работу без ожидания ответа, позволяя потоку сразу двигаться дальше

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

Интеграция в архитектуру потока

Узлы Вебхук функционируют как конечные точки, которые преобразуют обработанные данные устройств во внешние API-вызовы. В отличие от узлов узел Передачи Данных, которые непрерывно передают весь поток данных устройств, Вебхук выполняет целевые API-запросы с точно настроенными пакетами данных. Такая архитектура позволяет:

• Автоматизацию по событиям: запускать внешние рабочие процессы на основе состояний устройства, вычисляемых метрик или определённых шаблонов данных, выявленных ранее в потоке

• Выборочную передачу данных: отправлять во внешние системы только релевантные атрибуты, сокращая лишнюю передачу данных и затраты на API

• Параллельное выполнение: работать одновременно с другими выходными узлами, позволяя параллельно запускать Вебхук и непрерывную передачу данных в разные назначения

• Интеграцию с несколькими источниками: принимать входящие соединения из нескольких параллельных веток и получать доступ к атрибутам из всех подключённых узлов

Возможности узла

Узел Вебхук предоставляет:

• Выполнение HTTP POST-запросов: отправка настраиваемых HTTP POST-запросов на любую доступную конечную точку по протоколам HTTP или HTTPS (HTTPS рекомендуется)

• Динамическое формирование пакета данных: создание JSON-тела запроса с объединением статических значений и динамических атрибутов из любой части потока с использованием синтаксиса {{attribute_name}}

• Настройка пользовательских заголовков: поддержка до 10 пользовательских HTTP-заголовков для аутентификации и других специфичных требований API

• Поддержка вложенных атрибутов: использование сложных структур атрибутов, включая вложенные объекты и массивы, внутри JSON-пакета

• Независимое выполнение: срабатывание без ожидания ответа и без блокировки потока, что обеспечивает надёжную работу независимо от доступности внешней системы

Давайте рассмотрим, какие элементы использует этот узел и что можно настроить при работе с ним.

Шаги настройки

Укажите имя узла

Введите понятное имя, которое отражает назначение Вебхука.

• Используйте названия, которые указывают на целевой сервис или действие (например, «Уведомления о превышении скорости в Slack» или «Создание заявки в CRM»)

• Это имя отображается на диаграмме потока для удобной идентификации

Настройте URL конечной точки

Введите полный URL, на который будут отправляться POST-запросы.

• Укажите протокол: http:// или https:// (HTTPS настоятельно рекомендуется)

• Убедитесь, что URL указывает на корректную API-конечную точку, принимающую POST-запросы

• Пример: https://api.example.com/v1/webhooks/device-alerts

Укажите HTTP-заголовки

Добавьте все заголовки, необходимые для вашего целевого API.

Нажмите Добавить заголовок, чтобы создать пары ключ-значение для заголовков.
Все заголовки настраиваются пользователем, включая Content-Type. Распространённые заголовки включают:

• Content-Type: application/json (обязательно для JSON-пакетов)

• Authorization: Bearer <token> (для аутентификации в API)

• Пользовательские API-ключи или заголовки аутентификации в соответствии с требованиями конкретного сервиса

Нажмите значок удаления, чтобы удалить отдельные заголовки

Максимум поддерживается до 10 заголовков

Сформируйте тело запроса

Перейдите на вкладку Тело и задайте структуру JSON, которая будет отправляться на конечную точку:

• Введите корректный JSON-синтаксис в поле Тело

• Используйте {{attribute_name}}, чтобы ссылаться на любой атрибут из подключённых узлов

• Поддерживаются вложенные структуры JSON и массивы

• Ссылки на атрибуты работают и с вложенными путями (например, {{location.latitude}})

• Если указанный атрибут имеет значение null или не существует, в JSON будет отправлено значение null

Пример тела Вебхука с динамическими атрибутами:

{
  "alert_type": "speed_violation",
  "device_id": "{{device_id}}",
  "current_speed": "{{speed_mph}}",
  "threshold_exceeded": 80,
  "location": {
    "lat": "{{latitude}}",
    "lng": "{{longitude}}"
  },
  "timestamp": "{{message_time}}",
  "driver": "{{hardware_key}}"
}

Сохраните настройки

Нажмите Применить для применения настроек узла.

Поведение выполнения Вебхука

Вебхук выполняется без ожидания ответа от внешней конечной точки. Успешное или неуспешное выполнение запроса Вебхука не влияет на дальнейшую работу потока и не блокирует обработку данных другими узлами.

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

Вебхук и непрерывная передача данных

Узел Вебхук принципиально отличается от узла Передачи Данных по назначению и модели выполнения:

Выбирайте Вебхук, когда вам нужно запускать внешние сценарии автоматизации или отправлять только определённые атрибуты в API-конечные точки. Используйте узел Передачи Данных для непрерывной передачи данных на аналитические платформы или в системы мониторинга. Оба узла могут использоваться в одном и том же потоке.

Интеграция с внешними системами

Узлы Вебхук особенно эффективны для запуска действий по событиям в системах, которые предоставляют REST API. Распространённые сценарии интеграции включают:

• Платформы обмена сообщениями: отправка уведомлений в мессенджеры, когда состояния устройства соответствуют определённым критериям

• ERP-системы: синхронизация данных устройств с платформами планирования ресурсов предприятия для обновления уровней запасов, запуска процессов закупки или журналирования использования оборудования для планирования технического обслуживания

• Тикет-системы: автоматическое создание обращений в поддержку или сервисных заявок в CRM-платформах, когда обнаруживаются проблемы с устройством

• Сервисы уведомлений: запуск SMS, email или push-уведомлений через сервисы вроде Twilio, SendGrid или Firebase, когда превышены заданные пороги

• Бизнес-автоматизация: запуск рабочих процессов в инструментах вроде Zapier, Make (Integromat) или n8n на основе телеметрии устройств

• Телематические системы: запуск определённых действий или сценариев автоматизации в сторонних телематических решениях на основе обработанных данных, что позволяет реализовать событийные процессы, такие как перерасчёт маршрутов, уведомления водителей или обновление статусов во внешних системах управления автопарком

• Пользовательские приложения: запуск собственной бизнес-логики путём отправки событий устройств во внутренние API

Часто задаваемые вопросы

Как сделать так, чтобы Вебхук срабатывал только при определённых условиях?
Используйте узел логики IF/THEN для реализации условной логики перед узлом Вебхук. Узел логики IF/THEN может проверять атрибуты устройства и направлять данные в Вебхук только при выполнении заданных условий. Подробнее см. в разделе Логика IF/THEN.

Можно ли использовать несколько узлов Вебхук в одном потоке?
Да. Вы можете добавить несколько узлов Вебхук с разными настройками, чтобы запускать различные внешние системы на основе одних и тех же данных устройства. Каждый Вебхук срабатывает независимо, когда получает данные.

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

Как аутентифицироваться во внешних API?
Аутентификация полностью настраивается через пользовательские заголовки. Наиболее распространённые варианты:

• Bearer-токены: добавьте заголовок Authorization со значением Bearer your_token_here

• API-ключи: добавьте пользовательские заголовки в соответствии с требованиями вашего провайдера API

• Базовая аутентификация: добавьте заголовок Authorization со значением Basic base64_encoded_credentials

При отправке JSON-пакетов всегда добавляйте заголовок Content-Type: application/json.

Можно ли ссылаться на атрибуты из нескольких подключённых узлов?
Да. Узел Вебхук может получать доступ к атрибутам из любого узла, подключённого к нему, включая параллельные ветки. Если несколько узлов отправляют данные в Вебхук, он срабатывает один раз для каждого входящего сообщения и может использовать атрибуты из исходного пути этого сообщения.

Какие данные можно включить в тело Вебхука?
Вы можете включать любую комбинацию из следующего:

• Статические значения, заданные напрямую в вашей JSON-конфигурации

• Динамические атрибуты из потока с использованием синтаксиса {{attribute_name}}

• Вложенные атрибуты из сложных структур данных

• Атрибуты, вычисленные в узлах Вычисление Атрибута или обработанные через узлы логики IF/THEN

Тело должно быть корректным JSON. Если указанный атрибут не существует или содержит значение null, в JSON будет отправлено значение null.

Как протестировать конфигурацию Вебхука?
В настоящее время тестирование требует развернуть поток и проверить результат на стороне конечной точки назначения. Настройте Вебхук, сохраните поток и отправьте тестовые данные, чтобы убедиться, что внешняя система получает ожидаемый пакет данных. Во время разработки можно использовать сервисы для тестирования Вебхуков, такие как webhook.site или RequestBin, чтобы просматривать точные запросы, которые отправляются.