Mattermost Incoming Webhooks: From Token to Channel – A Practical Guide

Why Incoming Webhooks Matter

When you want an external service (CI/CD, monitoring, ticketing, etc.) to drop a message into a Mattermost channel without a full user account, Incoming Webhooks are your go‑to solution. They let you send a simple HTTP POST with JSON, and Mattermost posts it as a bot‑style message. The trick is keeping the token safe and knowing the limits of what you can do.

Core Concepts

• Webhook URL – a unique endpoint that contains a token. Anyone who knows the URL can publish to the channel.
• Overrides – optional JSON keys that let you change the displayed username, icon, and channel (if you have the right permissions).
• Markdown support – the text field can contain Mattermost‑compatible Markdown for rich formatting.
• Rate limiting – server‑side limits protect against flooding; the default is 10 k requests per minute per webhook but can be tuned.

Step‑by‑Step: Create and Test a Webhook

1. Create the Webhook – In Mattermost, navigate to System Console > Integrations > Incoming Webhooks (or Team > Integrations for a team‑scoped webhook). Click New Incoming Webhook, give it a name, choose the channel, and click Save. You’ll receive a URL like https://mattermost.example.com/hooks/abcd1234efgh5678. Keep this URL secret.

2. Prepare the Payload – A minimal JSON payload looks like this:

   {
     "text": "Hello, **Mattermost**!",
     "username": "CI Bot",
     "icon_url": "https://example.com/bot.png"
   }
   

   The username and icon_url override the defaults for this message only.

3. Send the Message – Run the following curl command from a terminal that has network access to the Mattermost server:

   curl \
     -X POST \
     -H "Content-Type: application/json" \
     -d '{"text": "Hello, **Mattermost**!", "username": "CI Bot", "icon_url": "https://example.com/bot.png"}' \
     https://mattermost.example.com/hooks/abcd1234efgh5678
   

   You should see the message appear instantly in the chosen channel.

4. Validate Security – Try sending the same payload to an invalid token, e.g. replace the token with invalidtoken. Mattermost should respond with a 404 status code and no message will appear. This confirms the token is required for authentication.

Trade‑offs and Limitations

Token Exposure

Because the token is embedded in the URL, any leak (e.g., in CI logs, public repos, or network sniffing) grants write access to the channel. Store the URL in a secrets manager and never echo it in build artifacts.

One‑Way Delivery

Incoming webhooks are strictly unidirectional. They cannot read channel history, fetch attachments, or respond to user actions like reactions. For bidirectional integration, consider using a Mattermost bot with a full API token.

Rate Limits and Abuse

By default, Mattermost limits a webhook to 10 k requests per minute. Exceeding this will result in HTTP 429 responses. If you need higher throughput, contact your Mattermost administrator to adjust the WebhookRateLimit setting, but be aware of the risk of flooding the channel.

Markdown and Formatting

While the text field supports Markdown, not all Markdown features (e.g., tables, code blocks with language specifiers) render identically to the web UI. Test your formatting in a staging channel before pushing to production.

Practical Checklist Before Production

• Store the webhook URL securely – use environment variables or a secrets vault.
• Verify the channel ID – double‑check that the webhook posts to the intended channel by sending a test message.
• Set a unique bot name – avoid collisions with other integrations.
• Implement retry logic – if your external service fails, retry with exponential backoff but respect the 429 responses.
• Monitor channel traffic – enable channel analytics or use Mattermost’s built‑in audit logs to detect unusual activity.

Conclusion

Incoming webhooks give you a lightweight, token‑based way to push notifications into Mattermost. They’re fast to set up, easy to test, and work well for CI alerts, monitoring pings, or any one‑way message push. Just guard the token, respect rate limits, and remember that these webhooks can’t read or respond to channel content. With that in mind, you can confidently automate your workflows without compromising channel integrity.