Automating Mattermost Workflows: Choosing Between Webhooks and Slash Commands

The Integration Dilemma: Push, Pull, or Command?

When automating a team's workflow in Mattermost, the primary challenge isn't usually writing the code—it's deciding how the communication should be triggered. If you set up an Incoming Webhook for every single alert, your channels become noisy and ignored. If you rely solely on Slash Commands, your automation is passive and requires a human to remember a specific syntax.

The goal is to balance proactive notifications (the system tells you something happened) with reactive utility (you ask the system to do something). Achieving this requires a strategic mix of Incoming Webhooks, Outgoing Webhooks, and Slash Commands.

Incoming Webhooks for Proactive Alerts

Incoming Webhooks are the simplest way to push data into Mattermost. They provide a unique URL that accepts JSON payloads. This is the ideal choice for CI/CD pipelines, monitoring alerts (like Prometheus or Grafana), or external script notifications.

Because these are one-way pushes, they are highly performant but lack context. They cannot "read" the channel; they can only write to it. To keep these from becoming spam, use Markdown formatting to create structured alerts with clear headers and actionable links.

Outgoing Webhooks and Slash Commands for Interactivity

When you need Mattermost to trigger an external action, you move from Incoming to Outgoing mechanisms. While they both send HTTP POST requests to your server, their triggers differ fundamentally:

• Outgoing Webhooks: Triggered by specific keywords or patterns in a channel. These are best for "listening" for specific events, such as a user mentioning a bot or using a specific hashtag.
• Slash Commands: Triggered by a specific command (e.g., /deploy-app) in the message box. These are superior for intentional user actions because they provide a structured interface and don't trigger accidentally during normal conversation.

Worked Example: Building a Deployment Trigger

Imagine a scenario where a developer needs to trigger a staging deployment. Using a Slash Command is safer than an Outgoing Webhook because it prevents accidental triggers during a chat about "deploying."

Configuration:

1. In the Mattermost System Console, create a new Slash Command.
2. Set the trigger word to /deploy-staging.
3. Set the request URL to your listener endpoint (e.g., https://api.yourcompany.com/mattermost/deploy).

The Request: When a user runs the command, Mattermost sends a POST request to your server. You must run your listener with permissions to accept incoming traffic from the Mattermost server IP. The payload will look like this:

{
  "user_id": "abc123xyz",
  "user_name": "jdoe",
  
"text": "production-branch",
  "channel_id": "chan456",
  "command": "/deploy-staging"
}

The Response: Your server should return a JSON response. If you return "response_type": "in_channel", everyone in the channel sees the result. If you use "response_type": "ephemeral", only the user who ran the command sees the confirmation.

Technical Trade-offs and Constraints

Integrating with Mattermost involves a few critical infrastructure constraints:

Feature	Primary Limitation	Risk/Mitigation
Incoming Webhooks	Rate Limiting	High-frequency alerts can be throttled; implement a queue on the sender side.
Outgoing Webhooks	Public Endpoint Requirement	Your listener must be reachable via HTTP/S. Use a secure tunnel or VPN for internal-only tools.
Payload Size	Capped JSON size	Avoid sending massive logs in a single webhook; send a summary and a link to the full log.

Verification and Validation

To verify your integration is functioning without risking production stability, use curl to simulate an Incoming Webhook from your terminal:

curl -X POST -H 'Content-Type: application/json' -d '{"text": "Test alert from terminal"}' [YOUR_WEBHOOK_URL]

Check the target channel for the message. If the message does not appear, verify that the webhook URL is active in the System Console and that your network allows outbound traffic to the Mattermost instance.

Rollback Procedure

Since these integrations do not modify the Mattermost database schema, rolling back consists of deleting the Webhook or Slash Command entry in the System Console. This immediately invalidates the token/endpoint and stops all associated traffic.