Интеграции

Интеграция — это внешний вызов, который приходит в компонент. Мессенджер присылает сообщение, платёжная система — уведомление, чужой сервис — вебхук. Для платформы все они одинаковы: HTTP-запрос, который ждёт ответа. Принцип один: контракт объявляет, среда даёт, код отвечает.

Эта глава — обзор того, как такие интеграции устроены технологически.

HTTP и вебхуки

HTTP — базовый канал. Компонент экспортирует wasi:http/handler и отвечает любому сервису, умеющему вызвать URL.

Вебхук — HTTP-запрос о событии. Отвечайте на него быстро и идемпотентно: подтвердите получение, а обработку выполните отдельно. Отправитель повторяет запрос, если ответа нет.

Проверяйте подпись до разбора тела. У отправителя есть секрет. Заголовок запроса содержит подпись этого тела. Компонент сверяет подпись и только потом доверяет событию.

Шаблон обработки события

Обработка любого входящего события укладывается в пять шагов.

Сверьте подпись или токен из заголовка.
Разберите тело события.
Проверьте идентификатор события в хранилище «ключ — значение»: если событие уже обработано, ответьте подтверждением и завершите обработку.
Запишите идентификатор и подтвердите получение.
Обработайте событие и отправьте исходящий вызов.

Шаги одинаковы для мессенджеров, платёжных систем и навыков. Меняются имена полей — не порядок. Идемпотентность опирается на хранилище «ключ — значение» из контракта: интерфейс объявлен, ключи событий — ваши.

Боты Telegram

Бот Telegram получает обновления вебхуком: Bot API присылает компоненту POST-запрос с JSON. Сокращённый пример тела:

{
  "update_id": 123456,
  "message": {
    "chat": { "id": 789 },
    "text": "привет"
  }
}

Ответ уходит через тот же API: компонент делает исходящий HTTP-запрос к методу sendMessage. Исходящие вызовы объявляются в контракте — без записи в контракте среда их не пропустит.

Telegram подписывает каждый вебхук секретным токеном в заголовке запроса. Сверяйте токен до обработки обновления.

MAX

MAX — мессенджер с открытым API для ботов. Схема та же: события доставки приходят вебхуком, ответы уходят исходящими HTTP-запросами. Отличаются детали — формат событий, правила подписи, повторные доставки. Сверяйтесь с актуальной документацией канала: API мессенджеров меняется быстрее, чем книги.

Навыки Алисы

Навык Алисы — HTTP-сервис диалога. Пользователь произносит запрос. Облако Алисы отправляет навыку POST-запрос с JSON: текст, контекст сессии, идентификаторы пользователя и диалога. Навык возвращает ответ — текст для произнесения и подсказки следующего шага.

Ответ навыка собирается из тех же частей, что любой HTTP-ответ: код, заголовки, тело с JSON. Тело описывает, что произнести, что показать и какие подсказки предложить пользователю.

Компонент с интерфейсом wasi:http годится на роль навыка целиком: контракт объявляет входящие запросы, код формирует ответ диалога. Храните состояние сессии в хранилище «ключ — значение», объявленном в контракте, — тогда повторные запросы диалога находят контекст.

Ограничение исходящих вызовов

Интеграция — это не только входящие события, но и исходящие вызовы. Оба направления видны в контракте.

Список адресатов сужается явно. В среде исполнения настраивается перечень разрешённых хостов для исходящих запросов компонента: вызов мимо списка отклоняется. Компонент бота просит ровно те хосты API, которыми пользуется, — и ни одного больше.

Так интеграция остаётся проверяемой: контракт перечисляет интерфейсы, конфигурация среды — адреса, журнал вызовов сходится с обоими.

Безопасность интеграций

Правила одни для всех каналов.

Разрешено только объявленное. Исходящие вызовы перечислены в контракте. Среда предоставляет ровно эти интерфейсы — и ничего больше.
Секреты — в конфигурации среды. Токены и ключи приходят значением из конфигурации, а не из артефакта. Конфигурация, секреты и разрешения остаются на стороне среды.
Подпись проверяется первой. Непроверенное событие не открывает базу данных и не меняет состояние.
Запрет по умолчанию. Файловая система, сеть, переменные окружения, системные часы запрещены, пока не объявлены в контракте.

Проверяемая интеграция — безопасная интеграция: правила видны в контракте до запуска.

Что дальше

«WebAssembly и WASI» — как контракт WIT объявляет возможности.
«Платформа» — реестр, из которого среда берёт компонент.

WasmBox — Документация