Post messages with a webhook

Quick start

1. 1

   Create the webhook

   In the desktop app, open your community's Manage Server → Webhooks, create a webhook, choose the channels it may post in and copy the URL for a channel. It has this shape:

   urlCopy

   https://mss.gs/api/v1/webhook/{webhook_guid}/{token}/{channel_guid}

2. 2

   Send a message

   Sign the JSON with the webhook's secret and POST it. A webhook made in the desktop app always has one: copy it from Webhook Secret in the webhook's settings.

   bashCopy

   BODY='{"content": "Build #1847 passed on main"}'
   SIG=$(printf '%s' "$BODY" | openssl dgst -sha256 -hmac "$MSSGS_WEBHOOK_SECRET" | sed 's/^.* //')
   
   curl -X POST "$MSSGS_WEBHOOK_URL" \
     -H "Content-Type: application/json" \
     -H "X-Mssgs-Signature: sha256=$SIG" \
     -d "$BODY"

3. 3

   Read the answer

   The response gives you the message id, and a callback_url to change the message later.

   jsonCopy

   {
     "success": true,
     "message_id": "aZZ1a2b-...",
     "callback_url": "https://mss.gs/api/v1/trigger-callback/8f14e45f-...",
     "stream_url": "https://mss.gs/api/v1/instant/6b1e...c0?token=a1b2c3d4-..."
   }

What you can send

A message is either the short form (text with a title and a colour) or a full card, and either can carry buttons and files. The name at the top of the card is always the webhook's own name. In the webhook's settings you also decide whether it may post images and mention people.

Short form

Enough for most alerts.

{
  "content": "Server backup completed at 03:00 UTC",
  "color": "green",
  "title": "Backup Bot"
}

A full card

Send a message_container for a card with a linked title, a subtitle, markdown, fields and images. Through a webhook a card takes type, color, title, title_url, sub_title, description, fields, avatar_url, image_url, image_base64, images and the loader fields. The status pill, badge, diff stats and folded reasoning are for command replies. Every field is on message cards.

jsonCopy

{
  "message_container": {
    "type": "embed_message",
    "color": "green",
    "title": "Build #1847 passed",
    "title_url": "https://ci.example.com/builds/1847",
    "description": "All 212 tests green on **main**.",
    "fields": [
      { "field": "Duration", "value": "2m 34s" },
      { "field": "Commit", "value": "1a2b3c4" }
    ]
  }
}

#deploys

Message from CI

Build #1847 passed

All 212 tests green on main.

Duration

2m 34s

Commit

1a2b3c4

09:12

Buttons

Add an actions array to put buttons under the message. How they work is on buttons.

Files

Post real files with a message: a log, a report, a screenshot. They show like any other attachment, as a download row or inline for images, video and audio. A message with only files is fine: leave out content and the card.

{
  "message_container": {
    "color": "orange",
    "title": "Log dump: ios",
    "description": "DMs stopped arriving after switching networks"
  },
  "attachments": [
    {
      "name": "mssgs-logs-20260803-141205.log",
      "content_base64": "MjAyNi0wOC0wMyAxNDoxMjowNSBbV1NdIGNvbm5lY3RlZAo=",
      "mime_type": "text/plain"
    }
  ]
}

Why url only takes mssgs addresses

A webhook URL often ends up pasted into other dashboards. A leaked one must not let someone make every member's app fetch a file from a server they picked. If your file lives elsewhere, send it as content_base64 and mssgs hosts it.

A failed upload does not fail the message

Files are checked up front but uploaded afterwards. If an upload fails, that file is left out and the rest of the message still posts, without an error: losing the file beats losing the report. If a file matters, check that it arrived.

A file from the command line

BODY='{"attachments":[{"name":"report.csv","content_base64":"'"$(base64 < report.csv | tr -d '\n')"'","mime_type":"text/csv"}]}'
SIG=$(printf '%s' "$BODY" | openssl dgst -sha256 -hmac "$MSSGS_WEBHOOK_SECRET" | sed 's/^.* //')

printf '%s' "$BODY" | curl -sS -X POST "$MSSGS_WEBHOOK_URL" \
  -H 'Content-Type: application/json' \
  -H "X-Mssgs-Signature: sha256=$SIG" \
  --data-binary @-

Signing requests

A webhook with a secret only accepts requests that prove they know it, and a webhook made in the desktop app always has one (Webhook Secret in its settings). Sign the raw request body with HMAC-SHA256 using the secret, and send the lowercase hex digest in the X-Mssgs-Signature header as sha256=<hex>.

import crypto from 'node:crypto';

const body = JSON.stringify({ content: 'Deploy finished' });
const signature = crypto.createHmac('sha256', process.env.MSSGS_WEBHOOK_SECRET)
  .update(body)
  .digest('hex');

await fetch(process.env.MSSGS_WEBHOOK_URL, {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'X-Mssgs-Signature': `sha256=${signature}`
  },
  body
});

GitHub's own X-Hub-Signature-256 header is accepted too, so a GitHub webhook with the same secret works as is. The signature has no timestamp, so it does not stop a captured request from being sent again: the URL stays the secret that matters.

Responses and errors

A message that was posted comes back with its id and a callback_url to update or delete it for 30 minutes.

{
  "success": true,
  "message_id": "aZZ1a2b-...",
  "callback_url": "https://mss.gs/api/v1/trigger-callback/8f14e45f-...",
  "stream_url": "https://mss.gs/api/v1/instant/6b1e...c0?token=a1b2c3d4-..."
}

HTTP/1.1 200 OK
Content-Type: application/json

{ "error": "ATTACHMENT_TOO_LARGE" }

const res = await fetch(webhookUrl, { method: 'POST', headers, body });
const reply = await res.json().catch(() => null);

// A rejected payload still comes back as 200: read the body.
if (!res.ok || (reply && reply.error)) {
  throw new Error(`webhook rejected: ${reply?.error ?? res.status}`);
}

When the message has buttons, the response also has a stream_url: a live stream of the replies, reactions and button presses on that message, open for 10 minutes, or an hour when you send "sse_event_extended_timeout": true. See live updates.

Status codes

Error codes

File errors

Limits

Requests are rate-limited. When you get a 429, wait before you send again, and group alerts that arrive in bursts into one message.

GitHub, UniFi and App Store Connect

Point one of these services at a webhook URL and mssgs recognises it and posts a proper card, with no payload to write. See integrations. These answer with {"success": true} and no callback URL.