Integrations

Mattermost provides powerful integration capabilities that allow you to connect with external tools, automate workflows, and extend functionality. Build custom integrations or use pre-built ones from the Mattermost Marketplace.

Integration Overview

Incoming Webhooks

Send messages to Mattermost from external applications

Outgoing Webhooks

Trigger external services when messages match patterns

Slash Commands

Execute custom commands directly from the message input

OAuth 2.0 Apps

Build third-party applications with secure user authorization

Incoming Webhooks

Send messages to Mattermost channels from external applications without requiring a Mattermost user account.

How Incoming Webhooks Work

Create an incoming webhook in Mattermost
Receive a unique webhook URL
POST JSON payloads to the URL from your application
Messages appear in the specified channel

Creating an Incoming Webhook

Navigate to Integrations in the main menu
Select Incoming Webhooks → Add Incoming Webhook
Configure:
- Title: Descriptive name for the webhook
- Description: Purpose and usage notes
- Channel: Default destination channel
- Lock to channel: Force all posts to specified channel
- Username: Display name for webhook posts
- Icon: Custom avatar for the webhook

Sending Messages

POST a JSON payload to the webhook URL:

curl -i -X POST -H 'Content-Type: application/json' \
  -d '{
    "text": "Hello from external app!",
    "channel": "town-square",
    "username": "MyBot",
    "icon_emoji": ":ghost:"
  }' \
  https://your-mattermost-server.com/hooks/xxx-generatedkey-xxx

Advanced Payload Options

{
  "text": "Main message text",
  "channel": "channel-name",
  "username": "CustomBot",
  "icon_url": "https://example.com/icon.png",
  "icon_emoji": ":chart_with_upwards_trend:",
  "attachments": [
    {
      "fallback": "test",
      "color": "#FF8000",
      "pretext": "Optional pretext",
      "text": "Detailed message text",
      "title": "Attachment Title",
      "title_link": "https://example.com",
      "fields": [
        {
          "short": false,
          "title": "Priority",
          "value": "High"
        }
      ],
      "image_url": "https://example.com/image.png"
    }
  ],
  "props": {
    "custom_field": "custom_value"
  }
}

Use message attachments to create rich, formatted notifications with fields, colors, and images.

Outgoing Webhooks

Trigger HTTP requests to external services when messages match specific criteria.

How Outgoing Webhooks Work

User posts message in Mattermost
Message matches trigger word or channel
Mattermost sends payload to configured callback URL(s)
External service processes request
Service can respond with message to post back

Creating an Outgoing Webhook

Navigate to Integrations → Outgoing Webhooks
Click Add Outgoing Webhook
Configure:
- Title: Webhook name
- Description: Purpose documentation
- Content Type: application/json or application/x-www-form-urlencoded
- Channel: Specific channel or leave blank for all
- Trigger Words: Words that activate webhook (comma-separated)
- Trigger When: Start of message or anywhere in message
- Callback URLs: One or more URLs to call

Trigger Words

Exact Match (start of message):

Trigger words: jenkins, deploy

Matches:
  "jenkins build project-alpha"  ✓
  "deploy production"            ✓
  
Doesn't match:  
  "run jenkins build"            ✗
  "let's deploy later"           ✗

Starts With (anywhere in message):

Matches partial words and any position:
  "jenkins" matches "jenkins123"
  "deploy" matches "deployment"

Outgoing Webhook Payload

Mattermost sends:

{
  "token": "webhook-token",
  "team_id": "team-id",
  "team_domain": "team-name",
  "channel_id": "channel-id",
  "channel_name": "channel-name",
  "timestamp": 1234567890,
  "user_id": "user-id",
  "user_name": "username",
  "post_id": "post-id",
  "text": "message text",
  "trigger_word": "matched-trigger",
  "file_ids": "file1,file2"
}

Response Format

Respond with JSON to post a message:

{
  "text": "Build started for project-alpha",
  "username": "Jenkins Bot",
  "icon_url": "https://example.com/jenkins.png",
  "type": "custom_jenkins",
  "response_type": "in_channel"
}

Outgoing webhooks only work in public channels. They must be enabled by system administrators in the configuration.

Slash Commands

Create custom commands that users can invoke directly from the message input box.

Built-in Commands

Mattermost includes many built-in slash commands:

/away                  - Set status to away
/dnd                   - Set Do Not Disturb status
/offline               - Set status to offline  
/online                - Set status to online
/code [text]           - Format text as code
/collapse              - Collapse all image previews
/expand                - Expand all image previews
/header [text]         - Set channel header
/purpose [text]        - Set channel purpose
/rename [name]         - Rename channel
/invite @user          - Invite user to channel
/join [channel]        - Join a channel
/leave                 - Leave current channel
/mute                  - Mute current channel
/search [term]         - Search for messages

Creating Custom Slash Commands

Navigate to Integrations → Slash Commands
Click Add Slash Command
Configure:
- Title: Command name for management
- Description: What the command does
- Command Trigger Word: The command (e.g., deploy)
- Request URL: Endpoint to receive command
- Request Method: POST or GET
- Response Username: Bot name for responses
- Response Icon: Bot avatar
- Autocomplete: Show in command autocomplete
- Autocomplete Hint: Usage hints (e.g., [environment])
- Autocomplete Description: Help text

Command Request

When user types /yourcommand arg1 arg2, Mattermost sends:

POST /your-endpoint
Content-Type: application/x-www-form-urlencoded

token=token-value
team_id=team-id
team_domain=team-name
channel_id=channel-id
channel_name=channel-name  
user_id=user-id
user_name=username
command=/yourcommand
text=arg1 arg2
trigger_id=trigger-id

Command Response

Simple text response:

{
  "text": "Command executed successfully!"
}

Rich response with attachments:

{
  "response_type": "in_channel",
  "text": "Deployment Status",
  "attachments": [
    {
      "text": "✅ Production deployed successfully",
      "color": "#00FF00"
    }
  ]
}

Response Types:

ephemeral (default): Only visible to command user
in_channel: Visible to everyone in channel

Use ephemeral responses for errors or private information, and in_channel responses for results everyone should see.

OAuth 2.0 Applications

Build third-party applications that integrate with Mattermost using OAuth 2.0 for secure authentication.

Registering an OAuth App

Navigate to Integrations → OAuth 2.0 Applications
Click Add OAuth 2.0 Application
Configure:
- Display Name: Application name
- Description: App purpose
- Homepage: Application website
- Callback URLs: Redirect URIs after authorization
- Icon URL: Application logo

OAuth 2.0 Flow

Authorization Request:

GET /oauth/authorize?
  response_type=code&
  client_id=YOUR_CLIENT_ID&
  redirect_uri=YOUR_REDIRECT_URI&
  state=RANDOM_STATE

User Authorizes: User logs in and grants permissions
Authorization Code: Redirect to callback with code

https://your-app.com/callback?code=AUTH_CODE&state=RANDOM_STATE

Exchange for Access Token:

curl -X POST https://your-mattermost.com/oauth/access_token \
  -d "grant_type=authorization_code&
      client_id=YOUR_CLIENT_ID&
      client_secret=YOUR_CLIENT_SECRET&
      code=AUTH_CODE&
      redirect_uri=YOUR_REDIRECT_URI"

Use Access Token:

curl https://your-mattermost.com/api/v4/users/me \
  -H "Authorization: Bearer ACCESS_TOKEN"

Outgoing OAuth Connections

Securely connect outgoing webhooks and slash commands to OAuth-protected external services.

Use Cases

Webhooks to services requiring OAuth (GitHub, GitLab, etc.)
Slash commands calling protected APIs
Automatic token refresh
Centralized credential management

Configuration

System admin enables outgoing OAuth connections
Configure OAuth connection with:
- Client ID and Secret
- Authorization and Token URLs
- Scopes required
- Audience/Resource URL patterns
Webhooks/commands automatically use connection when calling matching URLs

Outgoing OAuth connections require system administrator configuration and are available in specific Mattermost editions.

Bot Accounts

Create dedicated bot accounts for integrations:

Cannot log in via UI (token-only access)
Identified with BOT badge
Don’t count against user licenses
Perfect for webhooks and automation
Can be assigned to specific integrations

Creating a Bot Account

Navigate to Integrations → Bot Accounts
Click Add Bot Account
Configure:
- Username: Bot username
- Display Name: Friendly name
- Description: Bot purpose
- Icon: Bot avatar
- Role: Bot permissions
Receive access token for API calls

# Use bot token for API requests
curl -H "Authorization: Bearer bot-access-token" \
  https://your-mattermost.com/api/v4/posts

Interactive Messages

Create messages with buttons and menus that trigger actions:

{
  "attachments": [
    {
      "text": "Approve deployment to production?",
      "actions": [
        {
          "name": "Approve",
          "integration": {
            "url": "https://your-app.com/approve",
            "context": {
              "deployment_id": "12345"
            }
          }
        },
        {
          "name": "Reject",
          "style": "danger",
          "integration": {
            "url": "https://your-app.com/reject",
            "context": {
              "deployment_id": "12345"
            }
          }
        }
      ]
    }
  ]
}

When user clicks button, Mattermost POSTs to the integration URL with context.

Message Menus

Add dropdown menus to messages:

{
  "attachments": [
    {
      "text": "Select environment:",
      "actions": [
        {
          "name": "Select environment",
          "integration": {
            "url": "https://your-app.com/select"
          },
          "type": "select",
          "options": [
            {"text": "Development", "value": "dev"},
            {"text": "Staging", "value": "staging"},
            {"text": "Production", "value": "prod"}
          ]
        }
      ]
    }
  ]
}

Dialog Boxes

Open interactive forms for complex user input:

{
  "trigger_id": "trigger-id-from-slash-command",
  "url": "https://your-app.com/submit",
  "dialog": {
    "title": "Create Deployment",
    "introduction_text": "Deploy to selected environment",
    "elements": [
      {
        "display_name": "Environment",
        "name": "environment",
        "type": "select",
        "options": [
          {"text": "Staging", "value": "staging"},
          {"text": "Production", "value": "prod"}
        ]
      },
      {
        "display_name": "Version",
        "name": "version",
        "type": "text",
        "placeholder": "e.g., v1.2.3"
      }
    ],
    "submit_label": "Deploy"
  }
}

Dialogs must be opened within 3 seconds of receiving a trigger_id from a slash command or interactive message.

Integration Best Practices

Security

Validate webhook tokens - Always verify incoming requests
Use HTTPS - Encrypt data in transit
Store secrets securely - Never commit tokens to version control
Limit permissions - Use least privilege principle
Rotate tokens regularly - Update integration credentials periodically

Performance

Respond quickly - Webhooks timeout after 30 seconds
Use async processing - Return 200 OK immediately, process later
Implement retries - Handle temporary failures gracefully
Rate limiting - Respect API rate limits
Batch operations - Combine multiple updates when possible

User Experience

Clear error messages - Help users understand what went wrong
Consistent formatting - Use similar styles across integrations
Helpful usernames - Make bot identity clear
Rich attachments - Use colors and formatting effectively
Ephemeral responses - Don’t spam channels with errors

Marketplace

Discover pre-built integrations in the Mattermost Marketplace:

GitHub - Repository notifications and actions
GitLab - Merge requests and pipeline updates
Jira - Issue tracking and updates
Jenkins - Build notifications and triggers
Zoom - Video meeting integration
And 700+ more integrations

Browse integrations at https://mattermost.com/marketplace/

Plugins - Extend Mattermost with custom functionality
Workflows - Automate processes within Mattermost
Messaging - Core communication features
Channels - Integration destinations

Overview

Core Features

Administration

​Integration Overview

Incoming Webhooks

Outgoing Webhooks

Slash Commands

OAuth 2.0 Apps

​Incoming Webhooks

​How Incoming Webhooks Work

​Creating an Incoming Webhook

​Sending Messages

​Advanced Payload Options

​Outgoing Webhooks

​How Outgoing Webhooks Work

​Creating an Outgoing Webhook

​Trigger Words

​Outgoing Webhook Payload

​Response Format

​Slash Commands

​Built-in Commands

​Creating Custom Slash Commands

​Command Request

​Command Response

​OAuth 2.0 Applications

​Registering an OAuth App

​OAuth 2.0 Flow

​Outgoing OAuth Connections

​Use Cases

​Configuration

​Bot Accounts

​Creating a Bot Account

​Interactive Messages

​Message Menus

​Dialog Boxes

​Integration Best Practices

​Security

​Performance

​User Experience

​Marketplace

​Related Features

Build docs developers (and LLMs) love

Integration Overview

Incoming Webhooks

How Incoming Webhooks Work

Creating an Incoming Webhook

Sending Messages

Advanced Payload Options

Outgoing Webhooks

How Outgoing Webhooks Work

Creating an Outgoing Webhook

Trigger Words

Outgoing Webhook Payload

Response Format

Slash Commands

Built-in Commands

Creating Custom Slash Commands

Command Request

Command Response

OAuth 2.0 Applications

Registering an OAuth App

OAuth 2.0 Flow

Outgoing OAuth Connections

Use Cases

Configuration

Bot Accounts

Creating a Bot Account

Interactive Messages

Message Menus

Dialog Boxes

Integration Best Practices

Security

Performance

User Experience

Marketplace

Related Features