Mattermost Incoming Webhooks for Automated Channel Alerts

The problem: your pipeline finishes, but the channel stays silent

A CI/CD job completes, a monitoring check fails, or a ticket changes status, and no one in the Mattermost channel knows until someone opens a dashboard. Manually copying updates is slow and easy to miss. You need a lightweight, one-way path from an external system into a specific Mattermost channel.

The useful takeaway: Mattermost incoming webhooks let an external system send an HTTPS POST with a JSON body to a unique URL, and Mattermost posts the message to the channel you selected when you created the webhook. You do not need a bot account or plugin for simple notifications.

What an incoming webhook does

An incoming webhook is a unique HTTPS URL provided by Mattermost. When your system POSTs JSON to that URL, Mattermost creates a message in the webhook's bound channel. The payload can include plain text, a custom username, an icon URL, and attachments with fields and colors.

This is one-way only. A webhook can send messages, but it cannot read channel history, reply to threads, or handle button clicks. For those capabilities, you need a bot account or a Mattermost plugin. Incoming webhooks differ from outgoing webhooks, which forward channel events from Mattermost to an external service.

Create a webhook and treat the URL like a credential

Open the channel where messages should appear, then use Mattermost Integrations to create an incoming webhook. Copy the URL immediately and store it securely. The permissions required to create a webhook, and the exact location for enabling or disabling them in the System Console, depend on your Mattermost version and deployment type. If the option is not visible, ask a system administrator or consult your version-specific documentation.

A webhook URL functions like a bearer token: anyone who knows it can post messages to that channel. Never commit it to source control, and rotate it if you suspect it has leaked. A Mattermost system administrator can disable incoming webhooks globally at any time, which would break the integration without changing your code.

Worked example: post a deployment alert

Run this from a terminal or CI host that can reach your Mattermost instance over outbound HTTPS. Replace every placeholder with your own values.

curl -X POST 'https://mattermost.example.com/hooks/YOUR_WEBHOOK_ID' \
  -H 'Content-Type: application/json' \
  -d '{
    "text": ":rocket: Deployment complete",
    "username": "ci-bot",
    "icon_url": "https://example.com/ci-icon.png",
    "attachments": [
      {
        "color": "#4caf50",
        "fields": [
          { "short": false, "title": "Service", "value": "payments-api" },
          { "short": true, "title": "Environment", "value": "production" },
          { "short": true, "title": "Version", "value": "1.4.2" }
        ]
      }
    ]
  }'

Where to run: any build host, laptop, or CI runner with network reachability to the Mattermost server. Required permissions: outbound HTTPS access to the instance, and permission in Mattermost to create incoming webhooks. Expected check: the server returns an HTTP 200 response and the message appears in the target channel. If you receive an error or no message appears, confirm the webhook is still enabled and that you copied the full URL correctly. Do not log the real webhook URL in public CI output; pass it from a masked secret variable instead.

Trade-offs and limitations

• Channel-bound. A webhook posts to the channel selected at creation. To post to another channel, create another webhook.
• One-way only. You cannot read replies or channel history through the same webhook.
• No interactivity. Attachment buttons can be included in the payload, but handling clicks requires a bot account or plugin.
• Central kill switch. A system administrator can disable incoming webhooks globally, and default limits may differ between cloud and self-hosted deployments.

Verify the result

After the test POST, open the target channel in Mattermost and confirm the message and attachment fields appear. In your Mattermost System Console integrations settings, verify that incoming webhooks remain enabled for your deployment.

Roll back if needed

Creating a webhook changes state because it generates a new URL that can post to your channel. To roll back, delete the webhook from Mattermost Integrations. If you suspect abuse, ask a system administrator to disable incoming webhooks globally.

Closing

Incoming webhooks are a practical, low-overhead way to push automated alerts into Mattermost. Start with one webhook for one channel, secure the URL like a credential, and confirm the HTTP 200 response before depending on it in production.