Какие коннекторы могут получать входящие webhook-события?

Доступные коннекторы и типы событий перечислены в форме задачи при выборе триггера по событию. Например, можно разобрать входящее сообщение Umnico или отреагировать на новую сделку в Битрикс24. Новые отзывы, вопросы, чаты и заказы Wildberries проверяет задача по расписанию.

Как запустить задачу автоматически при поступлении события?

Создайте в приложении задачу с триггером по событию: выберите сервис и типы событий, на которые реагировать, или все его события. Чтобы сузить, какие полезные нагрузки запускают задачу, попросите агента в чате добавить ей условия фильтра. Когда приходит подходящее событие, задача выполняется с этим событием на входе.

Вебхуки и события

Коннекторы не только вызываются наружу: многие получают входящие события (новая сделка в CRM, входящее сообщение, смена статуса заказа). Эти события попадают в локальный журнал и могут запускать автоматические задачи, так что вы реагируете на происходящее во внешнем сервисе, не опрашивая его.

Как проходит входящее событие

Регистрация webhook-URL

У сервисов с автоматической настройкой, например Umnico и Wazzup, платформа регистрирует вебхук при подключении. Сохранение ключа и регистрация вебхука имеют отдельные исходы. Если провайдер отклонил регистрацию, причину и доступное действие можно посмотреть в карточке подключения. Для сервисов с ручной настройкой скопируйте адрес вебхука из карточки и вставьте его в кабинете провайдера.

Провайдер шлёт POST-событие

Когда на стороне провайдера что-то происходит, он шлёт POST на этот URL. Платформа проверяет токен в URL и подпись, если провайдер подписывает запросы, отбрасывает повторы и записывает событие в журнал.

Отреагировать

Пусть сохранённая задача запускается автоматически в момент поступления подходящего события.

Webhook-URL

У каждого подключения, которое принимает входящие события, свой случайный webhook-URL. Храните его как пароль. При ручной настройке карточка показывает адрес тому, кто может управлять подключением (его владельцу или роли с правом управлять интеграциями). Приложение читает адрес из GET /api/v1/credentials/{service}/webhook/url, а состояние регистрации из GET /api/v1/credentials/{service}/webhook/status. Этот API открыт сессии вошедшего пользователя. Ключ организации получит 401.

При ручной настройке вставьте адрес ровно в том виде, в каком его скопировали. Токен маршрута уже входит в адрес. Ключ API и ключ подписи провайдера вводятся отдельно, если сервис их запрашивает.

В Мегаплане откройте Настройки → Приложения, откройте нужное приложение и вставьте адрес в поле «URL принимающий события». Отметьте нужные потоки, сохраните настройки и создайте событие в одном из выбранных потоков. Документация Мегаплана

При ручной настройке карточка показывает «адрес ещё не получал событий», пока не было ни одной подтверждённой доставки. Если провайдер уже отправлял события, проверьте, какой адрес указан у него в кабинете.

Адрес занят другим сервисом

У некоторых провайдеров адрес вебхука один на весь аккаунт: у wazzup он один на API-ключ, и тот же ключ часто уже держит CRM клиента. Такой слот платформа сначала читает и чужой адрес не перезаписывает: строка коннектора и его карточка показывают, на какой хост сейчас уходят события, и кнопку «Заменить адрес». После замены прежний сервис перестаёт получать события, поэтому замена требует подтверждения. Приложение делает это запросом POST /api/v1/credentials/{service}/webhook/register с телом {"replace_foreign": true} в сессии вошедшего пользователя; ключ организации его вызвать не может. Удалить адрес у Wazzup нельзя, поэтому при отключении коннектора платформа трогает слот, только если там её собственный адрес: возвращает прежний адрес, если заменила его с вашего подтверждения, а иначе выключает свои подписки.

Замена URL

Старый URL продолжает принимать события 24 часа после смены. При ручной настройке администратор организации может выпустить новый URL в карточке подключения. Карточка показывает, когда истечёт старый адрес. До этого момента вставьте новый URL в кабинете провайдера. При смене адреса через POST /api/v1/credentials/{service}/webhook/rotate для автонастраиваемого сервиса платформа сама регистрирует новый адрес у провайдера.

Проверка и доставка

Подпись. Помимо токена в URL, платформа проверяет подпись провайдера над исходным телом запроса по схеме этого провайдера, если он подписывает запросы. Запрос с неверной подписью отклоняется и в журнал не попадает.
Формат. Тело в JSON или application/x-www-form-urlencoded, размер тела ограничен.
Ответ. Принятая доставка получает 2xx с {"outcome": "…"}, одним словом из закрытого словаря ниже. Отказ это 4xx/5xx, а не 200 с ошибкой внутри.
Ответ и повторы. Проверенная доставка получает 200 с outcome: "received", как только событие записано, а обработка идёт сразу после ответа. Если обработка упала, мы повторяем её сами с растущей паузой (от минуты до часа, всего около шести часов), и провайдеру переотправлять не нужно. Повтор уже обработанного id доставки получает outcome: "duplicate" и задачу не запускает, повтор того, что ещё обрабатывается или ждёт нашего повтора, получает received. 503 значит, что событие не удалось записать, и провайдеру стоит повторить. 4xx бывает только на неизвестном адресе, неверной подписи или теле, которое не JSON и не форма.
Защита от петель. Частые события по одной сущности подряд задачи не запускают: так ответ агента в тот же сервис не зацикливается.
Без подходящей задачи событие всё равно остаётся в журнале, с outcome: "no_action".

outcome	Значение
`received`	Событие записано и будет обработано сразу после ответа, при сбое повтор идёт на нашей стороне.
`accepted`	Подходящие задачи поставлены в очередь.
`duplicate`	Эта доставка уже обработана, задача повторно не запускается.
`handled`	Событие обработал собственный обработчик коннектора (например, ответ в мессенджере).
`handler_declined`	Собственный обработчик коннектора принял событие и не обработал его.
`installation_processed`	Событие установки GitHub App.
`no_org_context`	Адрес не называет организацию, для которой запускать задачи.
`loop_detected`	Поток событий по одной сущности распознан как цикл, задача не запускается.
`no_action`	На это событие не настроена ни одна задача, в журнал оно всё равно записано.
`event_skipped`	В доставке нет события, которое коннектор распознаёт.
`read_dropped`	Коннектор прочитал объект события и не нашёл, на что реагировать (ваш же ответ, пустое сообщение), задача не запускается.

Запуск задач по событиям

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

Сервис. Коннектор, чьи события запускают задачу.
Типы событий. На какие типы событий этого сервиса реагировать (например lead.status_changed у amocrm, deal.created у bitrix24), либо все события сервиса вместо перечисления. Нужно одно из двух; имя, которого сервис не шлёт и которого нет в журнале, задача не сохранит.
Условия фильтра (необязательно). Условия на исходное тело события от провайдера, каждое из поля (путь через точку, например message.chat.id), оператора (==, !=, >, <, >=, <= или contains, подстрока без учёта регистра) и значения. Все условия должны выполниться; отсутствующее поле не совпадает. Форма задачи их пока не редактирует: попросите агента в чате добавить их задаче.

На каждое совпавшее событие ставится отдельный запуск задачи. На вход он получает service, event_type, entity_id, entity_type и payload события. У avito, max_messenger, pachca и wazzup входящие сообщения идут агенту в чат. Личное сообщение в telegram уходит в задачу, только если у неё заданы условия фильтра.

У Umnico события идут в задачи. Выберите message.incoming для разбора новых сообщений или lead.changed.status для реакции на смену статуса обращения.

Webhook или schedule

Триггер webhook реагирует на внешнее событие в момент его возникновения; триггер schedule запускается по cron-расписанию (минимальный интервал пять минут). Выбирайте webhook, когда работа отвечает на случившееся, и schedule, когда она должна идти по часам. Оба выбираются при создании задачи в приложении.