​
Введение

Триггеры доступны только для приложений Workflow.
Вебхук позволяет одной системе автоматически отправлять данные другой в реальном времени. Когда происходит определённое событие, исходная система упаковывает его подробности в HTTP-запрос и отправляет его на заданный URL, предоставленный системой-получателем. По тому же принципу webhook-триггеры позволяют запускать ваш рабочий процесс в ответ на события сторонних систем. Вот как с ними работать:
  1. Когда вы добавляете webhook-триггер в рабочий процесс, генерируется уникальный URL вебхука — выделенный эндпоинт, который прослушивает внешние HTTP-запросы.
    Для самостоятельно размещённых развёртываний вы можете изменить базовый префикс этого URL через переменную среды TRIGGER_URL.Убедитесь, что он указывает на публичный домен или IP-адрес, доступный внешним системам.
  2. С помощью этого URL вы создаёте вебхук, подписывающийся на события, которые хотите отслеживать во внешней системе. Затем вы настраиваете webhook-триггер, чтобы определить, как он обрабатывает входящие запросы и извлекает их данные.
    Для тестирования всегда используйте тестовый URL вебхука, чтобы отделить тестовые данные от рабочих.
    Тестовый URL вебхука
  3. Когда происходит событие, на которое оформлена подписка, внешняя система отправляет HTTP-запрос с данными события на указанный URL вебхука. После того как запрос получен и успешно обработан, запускается ваш рабочий процесс, а данные указанного события извлекаются в переменные, на которые могут ссылаться нижестоящие узлы.
Если для вашей целевой внешней системы есть готовый триггер-плагин, рекомендуем использовать вместо этого триггер плагина.

​
Добавление webhook-триггера

На холсте рабочего процесса нажмите правой кнопкой мыши и выберите Добавить узел > Старт > Webhook-триггер.
Рабочий процесс может содержать несколько webhook-триггеров. Если такие ветви триггеров используют одни и те же нижестоящие узлы, добавьте Агрегатор переменных, чтобы свести их воедино и не дублировать эти узлы на каждой ветви.

​
Настройка webhook-триггера

Вы можете определить, как webhook-триггер обрабатывает входящие HTTP-запросы, в том числе:
  • Ожидаемый HTTP-метод для URL вебхука
  • Content-type запроса
  • Данные, которые вы хотите извлечь из запроса
  • Ответ, отправляемый внешней системе при успешном запуске рабочего процесса
Чтобы протестировать неопубликованный webhook-триггер, сначала обязательно нажмите Запустить этот шаг или выполните тестовый запуск всего рабочего процесса. Это переводит триггер в режим прослушивания, чтобы он мог принимать внешние запросы. Иначе ни один запрос не будет перехвачен.

​
HTTP-метод

Чтобы входящий запрос был успешно получен, нужно указать, какой HTTP-метод принимает URL вебхука. Выбранный здесь метод должен совпадать с тем, который использует внешняя система для отправки запросов, иначе запросы будут отклонены.
Обычно эту информацию можно найти в документации по вебхукам внешней системы или в её интерфейсе настройки.

​
Content-Type

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

​
Параметры запроса, параметры заголовков и параметры тела запроса

Вы можете извлекать определённые данные из параметров запроса, заголовков и тела входящего запроса. Каждый извлечённый параметр становится выходной переменной, которую можно использовать в рабочем процессе. Некоторые внешние системы ведут журнал доставки для каждого запроса, где можно просмотреть все данные, включённые в запрос, и решить, какие параметры извлечь. Также вы можете отправить тестовый запрос на webhook-триггер и проверить полученные данные запроса в журналах его последнего запуска:
  1. Создайте вебхук во внешней системе, используя предоставленный тестовый URL вебхука.
  2. Задайте в триггере правильный HTTP-метод и content-type.
  3. Нажмите значок Запустить этот шаг. Триггер начнёт прослушивать внешние запросы.
  4. Инициируйте во внешней системе событие, на которое оформлена подписка, чтобы она отправила HTTP-запрос на предоставленный URL вебхука.
  5. Перейдите на вкладку Последний запуск триггера и проверьте полученные данные запроса в разделе Ввод.
Имя переменной, заданное в триггере, должно совпадать с именем ключа соответствующего параметра в запросе.
  • Параметры в виде пар «ключ-значение», которые внешние системы добавляют к URL вебхука (после ?) при отправке запросов; каждая пара отделяется символом &.
  • Обычно это простые, нечувствительные идентификаторы или данные для фильтрации события.
  • Пример: из URL {webhook url}?userID=u-456&source=email вы можете извлечь userID (u-456) или source (email).
Настройки параметра Для каждого извлекаемого параметра вы можете указать следующее:
  • Имя переменной: имя ключа параметра во входящем запросе (например, userID в userID=u-456).
    Для параметров заголовков любой дефис (-) в имени переменной автоматически преобразуется в подчёркивание (_) в выходной переменной.
  • Тип данных: ожидаемый формат данных. Доступно только для параметров запроса и тела запроса, так как параметры заголовков всегда обрабатываются как строки.
  • Обязательный: требуется ли этот параметр для корректного выполнения рабочего процесса. Если во входящем запросе отсутствует какой-либо обязательный параметр, рабочий процесс не будет запущен.

​
Ответ

При успешном запуске рабочего процесса внешним HTTP-запросом внешней системе по умолчанию отправляется ответ 200 OK. Если внешней системе требуется определённый формат ответа об успехе, вы можете настроить код статуса и тело ответа. Ответ по умолчанию будет переопределён.
  • Код статуса: поддерживается любой код статуса в диапазоне [200, 399].
  • Тело ответа: поддерживается JSON или обычный текст.
В возвращаемом теле ответа содержимое не в формате JSON автоматически преобразуется в JSON.Например, OK будет обёрнуто как "message": "OK".
Следующие ответы об ошибках определяются системой и не подлежат настройке. Подробности ошибки можно найти в теле ответа.
  • 400 Bad Request
  • 404 Not Found
  • 413 Payload Too Large
  • 500 Internal Server Error

​
Тестирование webhook-триггера

Чтобы протестировать неопубликованный webhook-триггер, сначала нажмите Запустить этот шаг или выполните тестовый запуск всего рабочего процесса. Это переводит триггер в режим прослушивания, чтобы он мог принимать внешние запросы. Иначе входящие запросы не будут перехвачены.