Webhooks & Integraties

Bouw bots en integraties met mssgs webhooks

Aan de slag Incoming Webhooks Webhook Triggers Actions Voorbeelden

Aan de slag

Met mssgs webhooks kun je berichten sturen naar kanalen en interactieve bots bouwen die reageren op commands.

1

Maak een webhook aan

Ga naar Server Settings > Integraties en maak een nieuwe webhook of trigger aan.

2

Kopieer de URL

Kopieer de webhook URL of trigger GUID voor je integratie.

3

Start met bouwen

Stuur JSON payloads naar de webhook URL om berichten te posten.

Twee manieren om te integreren

Incoming Webhooks: Stuur berichten naar mssgs vanuit externe tools (CI/CD, monitoring, etc.)
Webhook Triggers: Reageer op commands en berichten met je eigen server.

Incoming Webhooks

Stuur berichten naar een kanaal via een webhook URL. Perfect voor CI/CD notificaties, monitoring alerts, en andere automatiseringen.

POST /server/:server_guid/webhook/:channel_guid

Request structuur

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

Simple Format

De eenvoudigste manier om een bericht te sturen.

Simple Message 
{
  "content": "Server backup completed at 03:00 UTC",
  "color": "green",
  "title": "Backup Bot"
}
Field Type Beschrijving
content string Bericht tekst (verplicht)
color string blue, green, orange, red, yellow, purple
title string Titel boven het bericht
title_url string Maakt titel een klikbare link
sub_title string Kleinere tekst onder de titel
avatar_url string Avatar afbeelding URL

Full Format (message_container)

Voor meer controle over het bericht, gebruik het volledige 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 Beschrijving
type string embed_message (default) of system_message
color string Accentkleur van het bericht
title string Titel van het bericht
description string Hoofd tekst (verplicht)
title_url string Link achter de titel
sub_title string Subtitel tekst
bot_name string Custom bot naam
avatar_url string Avatar afbeelding
fields array Key-value velden

Fields

Voeg gestructureerde key-value data toe aan je bericht.

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

Webhook Triggers

Bouw interactieve bots die reageren op commands en berichten. Wanneer een gebruiker een trigger activeert (bijv. /help), wordt jouw server aangeroepen en kun je een response terugsturen.

Hoe het werkt

1. Gebruiker typt /help in een kanaal
2. mssgs stuurt een request naar jouw webhook URL
3. Jouw server stuurt een JSON response terug
4. mssgs toont het bericht aan de gebruiker

Request die je ontvangt

Wanneer een trigger wordt geactiveerd, ontvang je deze 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

Wanneer getriggerd via een action button, bevat de request een 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 formaat

Stuur een JSON response terug om een bericht te tonen.

Basis response

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

Volledige 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 Beschrijving
message_container object Bericht configuratie (verplicht)
actions array Action buttons (zie Actions sectie)
visible_to_member_guids array Alleen deze members zien het bericht
ephemeral boolean Als true, bericht wordt niet opgeslagen

Timeout

Je webhook moet binnen 5 seconden responderen.

Actions

Voeg interactieve buttons toe aan je berichten. Gebruikers kunnen hierop klikken om follow-up acties te triggeren.

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 velden

Field Type Beschrijving
label string Button tekst (verplicht)
type string Action type (verplicht)
payload object Data die wordt meegegeven bij trigger

Action types

Type Beschrijving
trigger:{guid} Triggert een andere webhook trigger via GUID
url:{url} Opent een URL in een nieuw tabblad

Wat gebeurt er bij een action click?

Wanneer een gebruiker op "Check Status" klikt, ontvangt jouw webhook een nieuwe request met:

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

Rate limit

Action triggers zijn gelimiteerd tot 5 requests per 30 seconden per gebruiker.

Errors

Bij fouten ontvang je een JSON error response.

Error Response 
{
  "error": "ERROR_CODE"
}

Error codes

Code Beschrijving
INVALID_TOKEN Ongeldige authenticatie token
MISSING_REQUIRED_FIELDS Verplichte velden ontbreken in data
MISSING_CONTENT Bericht vereist content of message_container.description
UNSUPPORTED_GITHUB_EVENT GitHub event type niet ondersteund
UNSUPPORTED_UNIFI_PROTECT_EVENT UniFi Protect event niet ondersteund

Success response

Success 
{
  "success": true
}

Voorbeelden

Simple notificatie

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" }
    }
  }'

Gekleurde alert met 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 met 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: simpel

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

Trigger response: privebericht

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: interactief 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" }
    }
  ]
}

Speciale Webhooks

mssgs herkent automatisch bepaalde webhook types.

GitHub Webhooks

Automatisch gedetecteerd via de x-github-event header. Ondersteunde events: Push, Pull Requests, Issues, Releases, en meer.

UniFi Protect Webhooks

Automatisch gedetecteerd via user-agent: protect-alarm-manager header.

Vragen?

We helpen je graag verder met je integratie.

developers@mss.gs