Узел Webhook

Эта функциональность находится на завершающем этапе разработки и тестирования, она станет доступна очень скоро! Если вы хотите узнать больше или у вас есть вопросы Свяжитесь с нами!

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

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

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

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

Как работают узлы Webhook

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Узел Webhook предлагает:

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

• Динамическое формирование пейлоада: Создаёт JSON-тело запроса, объединяя статические значения с динамическими атрибутами из любой части потока с использованием $"attribute_name" синтаксиса

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

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

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

Параметры конфигурации

Узел Webhook позволяет задавать, как ваш поток будет взаимодействовать с внешними системами через HTTP API-вызовы.

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

Шаги конфигурации

1

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

Введите описательное имя, которое идентифицирует назначение webhook.

1. Используйте имена, которые указывают на целевой сервис или действие (например, "Slack Speed Alerts" или "CRM Ticket Creation")

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

2

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

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

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

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

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

3

Определите HTTP-заголовки

Добавьте любые заголовки, требуемые вашим целевым API.

1. Нажмите Add new чтобы создать пары ключ-значение для заголовков

2. Все заголовки настраиваются пользователем, включая Content-Type

3. Распространённые заголовки включают:

   1. Content-Type: application/json (требуется для JSON-пейлоадов)

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

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

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

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

4

Построение тела запроса

Задайте JSON-структуру, которая будет отправлена на конечную точку.

1. Введите корректный JSON в поле Body

2. Используйте $"attribute_name" чтобы ссылаться на любой атрибут из подключенных узлов

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

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

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

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

{
  "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"
}

5

Сохраните конфигурацию

Нажмите Применить чтобы сохранить настройки узла webhook.

Поведение выполнения webhook

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

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

Webhook vs непрерывная передача данных

Webhook фундаментально отличается от узла Output Endpoint по назначению и модели выполнения:

Webhook	узла Output Endpoint
Выполняет дискретные API-вызовы для каждого сообщения, отправляя настраиваемые пейлоады, которые вы определяете. Идеально подходит для запуска внешних действий, отправки уведомлений или передачи выборочных данных в REST API.	Поддерживает непрерывные потоки данных через MQTT, передавая полные данные устройств в формате Navixy Generic Protocol. Предназначен для постоянного сбора телеметрии и мониторинга в реальном времени.

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

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

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

• Платформы обмена сообщениями: Отправку уведомлений в Slack, Microsoft Teams, WhatsApp или Telegram, когда условия устройства соответствуют заданным критериям

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

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

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

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

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

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

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

Как запускать webhooks только при определённых условиях?

Используйте узел Logic чтобы реализовать условную логику перед webhook. Узел Logic может оценивать атрибуты устройства и направлять данные в webhook только при выполнении условий. Для подробностей см. документацию по узлу Logic.

Могу ли я использовать несколько узлов Webhook в одном потоке?

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

Что произойдёт, если запрос webhook завершится неудачей?

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

Как аутентифицироваться во внешних API?

Настройте аутентификацию полностью через пользовательские заголовки. Распространённые подходы:

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

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

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

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

Могу ли я ссылаться на атрибуты из нескольких подключенных узлов?

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

Какие данные я могу включить в тело webhook?

Вы можете включать любую комбинацию из:

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

• Динамических атрибутов из потока с использованием $"attribute_name" синтаксиса

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

• Атрибутов, рассчитанных в узлах Initiate Attribute или обработанных через узлы Logic

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

Как я могу протестировать конфигурацию webhook?

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