Webhook

Webhook

mumbot webhook is a long-running bot with a small HTTP API. An outside system (monitoring, CI, a script) sends one request with an API key and the bot posts the text into a Mumble channel. Nothing runs on the Mumble server.

Full reference: docs/webhook.md and docs/http-api.md.

Run it

mumbot webhook --config bot.toml

The bot reconnects after a dropped link. It exits non-zero only when the config is invalid, the listener cannot bind or the very first login fails.

Endpoints

Request	Key needed	Answer
POST /message	yes	Posts a message into a channel.
GET /channels	yes	Lists the channels this key may write to.
GET /health	no	Connection state, uptime.

Authentication: header X-API-Key: <key>. A key may only write to its own channels. A wrong or missing key gets 401.

Examples

KEY=REPLACE-WITH-A-LONG-RANDOM-KEY

# find the channel id
curl -s -H "X-API-Key: $KEY" http://127.0.0.1:8080/channels
# {"channels":[{"id":42,"name":"Lobby"}]}

# post a message
curl -s -X POST http://127.0.0.1:8080/message -H "X-API-Key: $KEY" \
  -d '{"channel": 42, "message": "**build failed** on `main`"}'
# {"delivered":true}

# health check
curl -s http://127.0.0.1:8080/health

message is 1 to 5000 characters, the body at most 20 KB.

Message format

Text is escaped; only a small Markdown subset becomes formatting.

Write	Becomes
**bold**, *italic*	bold, italic
`code` and fenced blocks	code
- item, # heading	list, heading
https://...	a link (other schemes stay text)

API keys

• One key per outside system, each with only the channels it needs.
• Generate with openssl rand -hex 32.
• Rate limit: 20 requests per minute per key by default.
• Keys are read at startup; to rotate, add the new block, restart, switch the caller, remove the old block.

More in Security. Setups to copy: Examples.