Using Mattermost Incoming Webhooks to Automate System Alerts

Problem: Manual System Alerts Are Fragile

When an external service—CI/CD, monitoring, or ticketing system—needs to notify a team, the traditional approach is to copy‑paste alerts into a chat or rely on a bot that polls the service. Polling wastes resources, introduces lag, and can miss critical events. Teams want a simple, reliable push mechanism that delivers structured information directly into the channel where people are already collaborating.

Thesis: Incoming Webhooks Give You a Push‑Based, Configurable Channel

Mattermost’s Incoming Webhooks let any HTTP client post JSON to a unique URL, which the server forwards as a message in a channel. The payload can override the bot’s username, avatar, and even include rich attachments. Because the webhook is a one‑way push, you avoid polling and get near‑real‑time notifications.

1. Create the Webhook in Mattermost

Navigate to System Console > Integrations > Incoming Webhooks (or Team Settings > Integrations > Incoming Webhooks for a team‑scoped URL). Click Create Incoming Webhook and fill in:

• Name – descriptive, e.g., CI‑Build‑Alerts
• Channel – where messages should appear
• Icon URL – optional custom avatar

After saving, Mattermost returns a Webhook URL that looks like https://mattermost.example.com/hooks/abcd1234. Keep this URL secret; anyone with it can post to the channel.

2. Build a JSON Payload

The minimal payload contains a text field. Additional fields customize the message:

Field	Description	Example
text	Primary message body	"Build succeeded for commit abc123"
username	Override bot name	"CI Bot"
icon_url	Override avatar	"https://example.com/bot.png"
attachments	Structured data block	See example below

Attachments let you add color, fields, and a footer. Example attachment:

{
  "fallback": "Build details",
  "color": "#36a64f",
  "title": "Build #42",
  "fields": [
    {"title": "Status", "value": "Success", "short": true},
    {"title": "Duration", "value": "3m 12s", "short": true}
  ],
  "footer": "CI System"
}

3. Send the Notification with curl

Run the following command on the machine that generates the event. Replace <WEBHOOK_URL> with the URL you captured:

curl -X POST -H "Content-Type: application/json" \
  -d '{
    "text": "Build succeeded for commit abc123",
    "username": "CI Bot",
    "icon_url": "https://example.com/bot.png",
    "attachments": [
      {
        "fallback": "Build details",
        "color": "#36a64f",
        "title": "Build #42",
        "fields": [
          {"title": "Status", "value": "Success", "short": true},
          {"title": "Duration", "value": "3m 12s", "short": true}
        ],
        "footer": "CI System"
      }
    ]
  }' \
  <WEBHOOK_URL>

After executing, the message should appear instantly in the target Mattermost channel with the overridden username and avatar, plus the formatted attachment.

4. Security & Rate‑Limiting Considerations

• URL Sensitivity – Treat the webhook URL like a password. Store it in a secrets manager and avoid committing it to source control.
• Rate Limiting – Mattermost may throttle high‑volume POST bursts. If you expect >100 messages per minute, coordinate with your Ops team or implement exponential back‑off in your sender script.
• Outgoing Webhooks – If you need Mattermost to call back to an external endpoint (e.g., for two‑way integration), you must configure an outgoing webhook and host a listener. This is a separate feature and not covered here.

Trade‑Offs & Limitations

Incoming webhooks are simple to set up and provide instant delivery, but they lack built‑in authentication beyond the secret URL. If you need stricter access control, consider using Mattermost’s Outgoing Webhooks or a reverse proxy that validates API keys before forwarding to the Mattermost URL.

Actionable Next Steps

1. Create a dedicated channel for system alerts.
2. Set up an incoming webhook and secure the URL.
3. Integrate the curl snippet into your CI pipeline or monitoring alert script.
4. Monitor message frequency; if you hit rate limits, implement back‑off or batch messages.
5. Document the webhook usage in your team’s Ops playbook.

With these steps, your team gets real‑time, structured notifications without polling or complex bot frameworks.