Вебхуки и события
Коннекторы не только вызываются наружу — многие получают входящие события (новая сделка в CRM, входящее сообщение, смена статуса заказа). Эти события попадают в локальный журнал и могут запускать автоматические задачи, так что вы реагируете на происходящее во внешнем сервисе, не опрашивая его.
Как проходит входящее событие
Регистрация webhook-URL
Для коннектора, поддерживающего входящие события, получите его webhook-URL и зарегистрируйте у провайдера (в настройках самого провайдера или в его консоли разработчика).
Провайдер шлёт POST-событие
Когда на стороне провайдера что-то происходит, он шлёт POST-событие на этот URL. Платформа валидирует запрос и записывает его в локальный журнал.
Посмотреть или отреагировать
Прочитайте, что пришло, через query_events, или пусть сохранённая задача запускается автоматически в момент поступления подходящего события.
Webhook-URL
Коннекторы, поддерживающие входящие события, выставляют webhook-URL на каждый сервис, который вы регистрируете у провайдера. Получите его программно:
Дальше провайдер шлёт POST-события на этот URL; платформа валидирует и записывает их. Поддерживает ли конкретный коннектор входящие события, объявлено в его паспорте — прочитайте его через describe_service, прежде чем настраивать webhook.
Журнал событий
query_events — это инструмент только для чтения поверх локального журнала входящих webhook-событий, уже сохранённых платформой, — а не живой вызов внешнего сервиса. Используйте его, чтобы посмотреть, что пришло (например, последние сообщения или обновления сделок), не перезапрашивая источник.
У него два действия: list — поиск событий с фильтрами, и get — получить полную полезную нагрузку одного события по event_id.
| Field | Type | Description |
|---|---|---|
| actionrequired | string | list — поиск с фильтрами, get — получить полную полезную нагрузку одного события по event_id. |
| service | string | Фильтр по коннектору — например telegram, amocrm, bitrix24, wazzup. |
| entity_type | string | Фильтр по сущности — message, lead, deal, contact, order. |
| event_type | string | Фильтр по событию — например message.received, deal.created, lead.updated. |
| event_id | string | UUID события — обязателен для action get. |
| days | number | Смотреть назад N дней (по умолчанию 7, максимум 90). |
| limit | number | Максимум результатов (по умолчанию 50, максимум 200). |
Запуск задач по событиям
Сохранённая задача может запускаться автоматически при поступлении подходящего события. Установите trigger_type: "webhook" и опишите, на какие события реагировать:
| Field | Type | Description |
|---|---|---|
| trigger_typerequired | string | Установите webhook для задач, управляемых событиями (альтернатива — schedule для задач по расписанию или manual только для ручного запуска). |
| trigger_config.servicerequired | string | Коннектор, чьи события запускают задачу. |
| trigger_config.event_types | string[] | На какие типы событий этого сервиса реагировать (например message.received, deal.created). |
| filter_conditions | object[] | Дополнительные условия на полезную нагрузку события перед запуском задачи. |
Когда входящее событие совпадает, задача выполняется с этим событием на входе — превращая любой webhook коннектора в автоматизацию.
Webhook или schedule
Триггер webhook реагирует на внешнее событие в момент его возникновения; триггер schedule запускается по cron-расписанию (минимальный интервал — пять минут). Выбирайте webhook, когда работа — это ответ на случившееся, и schedule, когда она должна идти по часам. См. Tasks API в интерактивном эксплорере.
FAQ
Какие коннекторы могут получать входящие webhook-события?
Коннекторы, которые заявляют поддержку входящих событий, выставляют webhook-URL на каждый сервис — типичные источники событий message, lead и deal — это мессенджеры и CRM: telegram, amocrm, bitrix24 и wazzup. Прочитайте паспорт сервиса через describe_service, чтобы узнать, поддерживает ли он входящие события.
Чем query_events отличается от обычного вызова коннектора?
query_events работает только для чтения поверх локального журнала уже сохранённых платформой событий — он никогда не вызывает внешний сервис. Обычный вызов connector_execute обращается к провайдеру вживую. Используйте query_events, чтобы посмотреть, что пришло; connector_execute — чтобы получить или записать данные.
Как долго хранятся входящие события?
query_events смотрит назад в окне, которое вы задаёте в days (по умолчанию 7, максимум 90). Чтобы получить полную полезную нагрузку конкретного события, запросите его по event_id с action: "get".
Как запустить задачу автоматически при поступлении события?
Создайте задачу с trigger_type: "webhook" и trigger_config, указав service и event_types, на которые реагировать. Добавьте filter_conditions, чтобы сузить, какие полезные нагрузки запускают задачу. Когда приходит подходящее событие, задача выполняется с этим событием на входе.
Частые вопросы
Какие коннекторы могут получать входящие webhook-события?
Коннекторы, которые заявляют поддержку входящих событий, выставляют webhook-URL на каждый сервис — типичные источники событий message, lead и deal — это мессенджеры и CRM: telegram, amocrm, bitrix24 и wazzup. Прочитайте паспорт сервиса через describe_service, чтобы узнать, поддерживает ли он входящие события.
Чем query_events отличается от обычного вызова коннектора?
query_events работает только для чтения поверх локального журнала уже сохранённых платформой событий — он никогда не вызывает внешний сервис. Обычный вызов connector_execute обращается к провайдеру вживую. Используйте query_events, чтобы посмотреть, что пришло; connector_execute — чтобы получить или записать данные.
Как долго хранятся входящие события?
query_events смотрит назад в окне, которое вы задаёте в днях (по умолчанию 7, максимум 90). Чтобы получить полную полезную нагрузку конкретного события, запросите его по event_id с action get.
Как запустить задачу автоматически при поступлении события?
Создайте задачу с trigger_type webhook и trigger_config, указав service и event_types, на которые реагировать. Добавьте filter_conditions, чтобы сузить, какие полезные нагрузки запускают задачу. Когда приходит подходящее событие, задача выполняется с этим событием на входе.