Интеграции

Вкладка «Интеграции» нужна администраторам для API-токенов, bot-аккаунтов, входящих webhook и исходящих webhook.

API-токены

API-токены используют тот же заголовок Authorization: Bearer, что и обычные сессии, но начинаются с fm_live_ или fm_test_. Полный токен показывается один раз, затем сервер хранит только хеш и отображаемый префикс.

  • Выдавайте минимальные scopes, например messages:write или webhooks:read.
  • admin:* используйте только для автоматизации, которой нужен доступ ко всему серверу.
  • Узкие API-токены всё равно проходят обычные проверки объектов, например membership в чате.
  • Отзывайте токен, когда клиент больше не нужен или есть риск утечки секрета.

Боты

Боты — это API-only пользователи с ролью bot. У них есть отображаемое имя, handle для упоминаний, аватар и профиль, но нет пароля и 2FA. Форма создания показывает первый bot-токен один раз. Бот может отправлять сообщения через REST API после того, как человек или администратор добавил его в чат; сам создавать чаты бот не может.

Callback бота привязывает HTTPS endpoint к одному боту. Он срабатывает только для этого бота, когда пользователь упоминает его handle в чате, где бот является участником. Секрет подписи показывается один раз, доставки подписываются теми же HMAC-заголовками, что и исходящие webhook, а логи хранятся отдельно для каждого callback.

Входящие webhook

Входящий webhook создаёт секретный URL для одного чата. Внешняя система может отправить { "text": "Build passed" } на этот URL, чтобы опубликовать сообщение. Узкие API-токены могут создавать webhook только для чатов, где владелец токена является участником. URL является секретом. Отзыв webhook сразу останавливает приём сообщений по этому URL.

Исходящие webhook

Исходящие webhook отправляют события message.created и bot.mentioned. В production нужен HTTPS; HTTP разрешён только для локальной разработки на localhost. Узкие API-токены должны указывать фильтр чатов, где владелец токена является участником; глобальные исходящие webhook требуют admin:*. Каждая доставка подписывается HMAC-SHA256 и содержит:

  • X-FM-Webhook-ID
  • X-FM-Webhook-Event
  • X-FM-Webhook-Timestamp
  • X-FM-Webhook-Signature в формате t=<timestamp>,v1=<hex>

Журнал доставок показывает каждую попытку, HTTP-код и время. Ошибочные доставки повторяются до трёх раз в рамках запущенного процесса сервера.

API-справочник

Полная OpenAPI-спецификация доступна по адресу /openapi.yaml и на странице OpenAPI-справочник.