Webhooks & Integrations

Build bots and integrations with mssgs webhooks

Getting Started Incoming Webhooks Webhook Triggers Actions Examples

Building a mini game?

Check out the WebGame Connect documentation for building HTML mini games on the mssgs platform.

Getting Started

With mssgs webhooks you can send messages to channels and build interactive bots that respond to commands.

1

Create a webhook

Go to Server Settings > Integrations and create a new webhook or trigger.

2

Copy the URL

Copy the webhook URL or trigger GUID for your integration.

3

Start building

Send JSON payloads to the webhook URL to post messages.

Two ways to integrate

Incoming Webhooks: Send messages to mssgs from external tools (CI/CD, monitoring, etc.)
Webhook Triggers: Respond to commands and messages with your own server.

Incoming Webhooks

Send messages to a channel via a webhook URL. Perfect for CI/CD notifications, monitoring alerts, and other automations.

POST /server/:server_guid/webhook/:channel_guid

Request structure

Request Body 
{
  "token": "server_management_token",
  "data": {
    "body": { ... },
    "headers": { ... },
    "webhook": {
      "name": "Webhook Name",
      "guid": "webhook_guid"
    }
  }
}

Simple Format

The simplest way to send a message.

Simple Message 
{
  "content": "Server backup completed at 03:00 UTC",
  "color": "green",
  "title": "Backup Bot"
}
Field Type Description
content string Message text (required)
color string blue, green, orange, red, yellow, purple
title string Title above the message
title_url string Makes the title a clickable link
sub_title string Smaller text below the title
avatar_url string Avatar image URL

Full Format (message_container)

For more control over the message, use the full message_container object.

Full Message Container 
{
  "message_container": {
    "type": "embed_message",
    "color": "blue",
    "title": "Order Update",
    "description": "Your order #12345 has been shipped!",
    "title_url": "https://example.com/orders/12345",
    "sub_title": "Estimated delivery: Tomorrow",
    "bot_name": "Order Bot",
    "fields": [
      { "field": "Status", "value": "Shipped" },
      { "field": "Tracking", "value": "ABC123456" }
    ]
  },
  "actions": [...]
}
Field Type Description
type string embed_message (default) or system_message
color string Accent color of the message
title string Title of the message
description string Main text (required)
title_url string Link behind the title
sub_title string Subtitle text
bot_name string Custom bot name
avatar_url string Avatar image
fields array Key-value fields

Fields

Add structured key-value data to your message.

Fields Array 
{
  "fields": [
    { "field": "Status", "value": "Completed" },
    { "field": "Duration", "value": "2m 34s" },
    { "field": "Environment", "value": "Production" }
  ]
}

Webhook Triggers

Build interactive bots that respond to commands and messages. When a user activates a trigger (e.g., /help), your server is called and you can send a response back.

How it works

1. User types /help in a channel
2. mssgs sends a request to your webhook URL
3. Your server sends a JSON response back
4. mssgs displays the message to the user

Request you receive

When a trigger is activated, you receive this data:

Trigger Request 
{
  "server_guid": "server-guid-here",
  "channel_guid": "channel-guid-here",
  "trigger_match": "/help",
  "message": {
    "id": "message-id",
    "content": "/help how do I create a channel?",
    "member_guid": "member-guid-here",
    "user_guid": "user-guid-here",
    "cms": 1234567890123
  }
}

Request via Action Button

When triggered via an action button, the request contains an action_payload:

Action Button Request 
{
  "server_guid": "server-guid-here",
  "channel_guid": "channel-guid-here",
  "trigger_match": "/help",
  "message": {
    "id": "message-id",
    "content": "[Action Triggered]",
    "member_guid": "member-guid-here",
    "user_guid": "user-guid-here",
    "cms": 1234567890123,
    "action_payload": {
      "custom_key": "custom_value"
    }
  }
}

Response format

Send a JSON response back to display a message.

Basic response

Simple Response 
{
  "message_container": {
    "description": "Here's your help content!"
  }
}

Full response

Full Response 
{
  "message_container": {
    "type": "embed_message",
    "color": "blue",
    "title": "Help",
    "description": "Here's how to create a channel...",
    "title_url": "https://docs.example.com/channels",
    "sub_title": "Channel Guide",
    "avatar_url": "https://example.com/bot-avatar.png"
  },
  "actions": [...],
  "visible_to_member_guids": ["member-guid-1"],
  "ephemeral": false
}
Field Type Description
message_container object Message configuration (required)
actions array Action buttons (see Actions section)
visible_to_member_guids array Only these members can see the message
ephemeral boolean If true, message is not saved

Timeout

Your webhook must respond within 5 seconds.

Actions

Add interactive buttons to your messages. Users can click on these to trigger follow-up actions.

Message with Actions 
{
  "message_container": {
    "title": "Order Status",
    "description": "Your order #12345 is being processed."
  },
  "actions": [
    {
      "label": "Check Status",
      "type": "trigger:abc123-trigger-guid",
      "payload": {
        "order_id": "12345"
      }
    },
    {
      "label": "View Order",
      "type": "url:https://example.com/orders/12345"
    }
  ]
}

Action fields

Field Type Description
label string Button text (required)
type string Action type (required)
payload object Data that is passed along with the trigger

Action types

Type Description
trigger:{guid} Triggers another webhook trigger via GUID
url:{url} Opens a URL in a new tab

What happens when an action is clicked?

When a user clicks "Check Status", your webhook receives a new request with:

  • message.content: "[Action Triggered]"
  • message.action_payload: { "order_id": "12345" }

Rate limit

Action triggers are limited to 5 requests per 30 seconds per user.

Errors

When errors occur, you receive a JSON error response.

Error Response 
{
  "error": "ERROR_CODE"
}

Error codes

Code Description
INVALID_TOKEN Invalid authentication token
MISSING_REQUIRED_FIELDS Required fields are missing in data
MISSING_CONTENT Message requires content or message_container.description
UNSUPPORTED_GITHUB_EVENT GitHub event type not supported
UNSUPPORTED_UNIFI_PROTECT_EVENT UniFi Protect event not supported

Success response

Success 
{
  "success": true
}

Examples

Simple notification

cURL 
curl -X POST https://mss.gs/server/SERVER_GUID/webhook/CHANNEL_GUID \
  -H "Content-Type: application/json" \
  -d '{
    "token": "your_token",
    "data": {
      "body": {
        "content": "Build completed successfully!"
      },
      "headers": {},
      "webhook": { "name": "CI Bot" }
    }
  }'

Colored alert with link

JSON Body 
{
  "token": "your_token",
  "data": {
    "body": {
      "content": "Build #123 completed!",
      "color": "green",
      "title": "CI/CD Pipeline",
      "title_url": "https://github.com/org/repo/actions/runs/123"
    },
    "headers": {},
    "webhook": { "name": "GitHub Actions" }
  }
}

Error alert

JSON Body 
{
  "token": "your_token",
  "data": {
    "body": {
      "message_container": {
        "type": "system_message",
        "color": "red",
        "title": "Alert: Database Error",
        "description": "Connection failed: timeout after 30s",
        "sub_title": "prod-db-01"
      }
    },
    "headers": {},
    "webhook": { "name": "Monitoring" }
  }
}

Deployment approval with actions

JSON Body 
{
  "token": "your_token",
  "data": {
    "body": {
      "message_container": {
        "color": "yellow",
        "title": "Deployment Request",
        "description": "User @johndoe requested a deployment to production."
      },
      "actions": [
        {
          "label": "Approve",
          "type": "trigger:approve-deploy-trigger-guid",
          "payload": { "deploy_id": "dep_123", "env": "production" }
        },
        {
          "label": "Reject",
          "type": "trigger:reject-deploy-trigger-guid",
          "payload": { "deploy_id": "dep_123" }
        },
        {
          "label": "View Changes",
          "type": "url:https://github.com/org/repo/compare/main...deploy"
        }
      ]
    },
    "headers": {},
    "webhook": { "name": "Deploy Bot" }
  }
}

Trigger response: simple

Trigger Response 
{
  "message_container": {
    "description": "Hello! How can I help you?"
  }
}

Trigger response: private message

Private Response 
{
  "message_container": {
    "description": "This is a private response only you can see."
  },
  "visible_to_member_guids": ["<member_guid from request>"],
  "ephemeral": true
}

Trigger response: interactive menu

Interactive Menu 
{
  "message_container": {
    "title": "What would you like to do?",
    "description": "Choose an option below:"
  },
  "actions": [
    {
      "label": "Get Help",
      "type": "trigger:help-trigger-guid"
    },
    {
      "label": "View Stats",
      "type": "trigger:stats-trigger-guid",
      "payload": { "period": "weekly" }
    }
  ]
}

Special Webhooks

mssgs automatically recognizes certain webhook types.

GitHub Webhooks

Automatically detected via the x-github-event header. Supported events: Push, Pull Requests, Issues, Releases, and more.

UniFi Protect Webhooks

Automatically detected via user-agent: protect-alarm-manager header.

Questions?

We're happy to help you with your integration.

developers@mss.gs