Входящие события → триггер

Внешнее событие превращается в триггер автоматизации через движок. Есть два пути поднять событие.

#1. Изнутри драйвера

Когда драйвер сам получает данные (поллер, свой webhook), он вызывает движок напрямую:

app(AutomationEngine::class)->handleConnectorEvent($workspace, 'telegram.message.received', [
    'collectionId' => $collId,   // опц.: для условий/скоупа
    'recordId'     => $recordId, // опц.: запись события
    'depth'        => 0,
    'payload'      => ['text' => $text, 'chatId' => $chatId], // → matchesTrigger()
]);

#2. Через общий inbound-endpoint

Для внешних систем, которые сами POST-ят события, есть единый публичный эндпоинт — отдельный контроллер под коннектор не нужен:

POST /integrations/inbound/{connection}

Чтобы его принимать, коннектор реализует App\Integrations\Contracts\InboundConnector:

interface InboundConnector {
    // Проверка подлинности (секрет/HMAC). false → 403.
    public function verifyInbound(IntegrationConnection $c, Request $r): bool;
    // Разбор запроса в события: [['type'=>, 'payload'=>, 'record'=>?…], …]
    public function parseInbound(IntegrationConnection $c, Request $r): array;
}

• Эндпоинт публичный и троттлится (throttle:inbound, 120/мин на ключ «подключение + IP»).
• Проверку подписи не переизобретайте: InboundSignature::verifySecret() / ::verifyHmac(). Секрет — $connection->ensureInboundSecret().

#Декларативный маппинг в запись

Чтобы не писать императивный код работы с записями, событие может нести карту record — движок сам сделает upsert записи и подставит её id (для условий и действий):

'record' => [
    'collectionId' => $connection->settings['products_collection_id'],
    'matchField'   => 'fld_sku',          // поле-ключ поиска существующей записи
    'matchValue'   => (string) $sku,
    'set'          => ['fld_qty' => $qty], // значения полей
    'title'        => $name,
],

Апсерт делает InboundRecordMapper: найти по matchField == matchValue (обновить) или создать (первый этап), слить set в данные, разослать realtime-событие.

#Что делает движок

1. Находит владеющий триггером коннектор.
2. Берёт включённые автоматизации с этим триггером в нужном скоупе.
3. Для каждой спрашивает matchesTrigger() (фильтры триггера).
4. Проверяет условия «Если» по записи, если есть recordId.
5. Ставит запуск в очередь.