Integrations

Integrations let external software participate in your workspace: receive events when things happen in chat, post messages as a bot, and answer slash commands your team runs from the composer. They’re managed by owners and admins under Settings → Integrations.

An integration is its own actor — it isn’t a member, doesn’t take a seat, and can only act inside your workspace. Its messages render in chat with an APP badge next to the bot’s name.

Create an integration

1. Open Settings → Integrations and choose Create.
2. Give it a name and description.
3. Set its webhook URL — where Knobs delivers events — and pick which events it subscribes to (new chat messages in channels, channel created).
4. Register any slash commands it should handle (name, description, usage hint).
5. Create it. Knobs shows the integration’s API token exactly once — copy it now and store it in your secret manager. Only a hint (knbi_…last4) is shown afterward.

Use the Ping button any time to send a signed test event to the webhook URL and confirm the receiver is wired up.

How delivery works

• Every event is a signed JSON POST to the webhook URL. Signatures are asymmetric (Ed25519): your receiver verifies them against the integration’s public key, fetched from a public keys endpoint — no shared secret to distribute.
• Failed deliveries retry automatically with backoff (roughly 1 minute → 5 minutes → 30 minutes → 2 hours) before being marked exhausted.
• The delivery log in the integration’s page records every attempt — status, response code, timing, and the request/response bodies — and any delivery can be redelivered with one click. Failures are kept visible, never silently dropped.

The bot API

With its token, an integration can call the bot API to:

• identify itself and its granted scopes,
• list the workspace’s channels, and
• post messages to a channel as the bot.

Rate limits are generous for normal use (60 requests/minute, 1 message/second per channel) and every response carries remaining-budget headers.

Slash commands

When a member types a registered /command in the chat composer, Knobs sends the invocation to the integration and shows the member a “sent” indicator. The integration replies whenever it’s ready — up to 15 minutes later — and its answer posts to the channel as a bot message. There’s no multi-second deadline to race.

Token hygiene

• Rotate an integration’s token at any time — the new token is shown once and the old one stops working immediately.
• Disable an integration to pause it (no deliveries, token rejected) without losing its configuration; delete removes it entirely.
• Tokens are stored hashed; nobody — including Knobs staff — can read one back after creation.

Tip

Building against the API yourself, as you rather than as a bot? Use a personal API key instead — see Account security.