Integrations

The Integrations tab is where admins create scoped API tokens, bot accounts, incoming webhooks, and outgoing webhooks.

API Tokens

API tokens use the same Authorization: Bearer header as normal sessions, but start with fm_live_ or fm_test_. The full token is shown once, then the server stores only a hash and a display prefix.

  • Use narrow scopes such as messages:write or webhooks:read.
  • Use admin:* only for automation that must manage the whole server.
  • Narrow API tokens still pass normal object checks such as chat membership.
  • Revoke a token from the table when a client is retired or a secret may have leaked.

Bots

Bots are API-only users with role bot. They have display names, mention handles, avatars, and profile cards, but no passwords or 2FA. The creation form returns the first bot token once. Bots can send messages through the REST API after a human or admin adds them to a chat; they cannot create chats themselves.

Bot callbacks attach an HTTPS endpoint to one bot. They fire only for that bot when a user mentions its handle in a chat where the bot is a member. The signing secret is shown once, deliveries are signed with the same HMAC headers as outgoing webhooks, and delivery logs are kept per callback.

Incoming Webhooks

Incoming webhooks create a secret URL for one chat. External systems can send { "text": "Build passed" } to that URL to post a message. Scoped API tokens can only create webhooks for chats they belong to. Treat the URL as a secret. Revoking the webhook immediately stops the URL from accepting messages.

Outgoing Webhooks

Outgoing webhooks deliver message.created and bot.mentioned events. Production webhooks must use HTTPS; HTTP is allowed only for localhost development targets. Narrow API tokens must use chat filters for chats they belong to; global outgoing webhooks require admin:*. Each delivery is signed with HMAC-SHA256 and includes:

  • X-FM-Webhook-ID
  • X-FM-Webhook-Event
  • X-FM-Webhook-Timestamp
  • X-FM-Webhook-Signature in t=<timestamp>,v1=<hex> format

The delivery log shows each attempt with status, HTTP code, and timestamp. Failed deliveries are retried up to three times by the running server process.

API Reference

The route-complete OpenAPI spec is available at /openapi.yaml and in the OpenAPI Reference.