Nachrichten per Webhook posten

Schnellstart

1. 1

   Webhook anlegen

   Öffne in der Desktop-App bei deiner Community Server verwalten → Webhooks, leg einen Webhook an, wähl die Kanäle, in die er posten darf, und kopier die URL für einen Kanal. Sie sieht so aus:

   urlKopieren

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

2. 2

   Eine Nachricht senden

   Signiere das JSON mit dem Secret des Webhooks und sende es per POST. Ein Webhook aus der Desktop-App hat immer eins: Kopier es unter Webhook-Secret in den Einstellungen des Webhooks.

   bashKopieren

   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

   Die Antwort lesen

   Die Antwort liefert dir die Nachrichten-ID und eine callback_url, mit der du die Nachricht später änderst.

   jsonKopieren

   {
     "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-..."
   }

Was du senden kannst

Eine Nachricht ist entweder die Kurzform (Text mit Titel und Farbe) oder eine vollständige Karte, und beide können Buttons und Dateien tragen. Der Name oben auf der Karte ist immer der Name des Webhooks selbst. In den Einstellungen des Webhooks legst du außerdem fest, ob er Bilder posten und Leute erwähnen darf.

Kurzform

Reicht für die meisten Alarme.

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

Eine vollständige Karte

Sende einen message_container für eine Karte mit verlinktem Titel, Untertitel, Markdown, Feldern und Bildern. Über einen Webhook nimmt eine Karte type, color, title, title_url, sub_title, description, fields, avatar_url, image_url, image_base64, images und die Loader-Felder an. Status-Pille, Badge, Diff-Statistik und eingeklappter Denkprozess sind Befehlsantworten vorbehalten. Alle Felder stehen unter Nachrichtenkarten.

jsonKopieren

{
  "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

Nachricht von CI

Build #1847 erfolgreich

Alle 212 Tests auf main grün.

Duration

2m 34s

Commit

1a2b3c4

09:12

Buttons

Füg ein actions-Array hinzu, um Buttons unter die Nachricht zu setzen. Wie sie funktionieren, steht unter Buttons.

Dateien

Poste echte Dateien mit einer Nachricht: ein Log, einen Bericht, einen Screenshot. Sie erscheinen wie jeder andere Anhang, als Download-Zeile oder, bei Bildern, Video und Audio, direkt in der Nachricht. Eine Nachricht nur mit Dateien ist in Ordnung: Lass content und die Karte weg.

{
  "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"
    }
  ]
}

Warum url nur mssgs-Adressen annimmt

Eine Webhook-URL landet oft in den Dashboards anderer Dienste. Wird sie geleakt, darf niemand damit die App jedes Mitglieds eine Datei von einem Server laden lassen, den er selbst ausgesucht hat. Liegt deine Datei woanders, sende sie als content_base64, und mssgs hostet sie.

Ein fehlgeschlagener Upload bringt die Nachricht nicht zum Scheitern

Dateien werden vorab geprüft, aber erst danach hochgeladen. Schlägt ein Upload fehl, fällt diese Datei weg, und der Rest der Nachricht wird trotzdem gepostet, ohne Fehler: Lieber die Datei verlieren als den Bericht. Ist eine Datei wichtig, prüf, ob sie angekommen ist.

Eine Datei von der Kommandozeile

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 @-

Requests signieren

Ein Webhook mit Secret nimmt nur Requests an, die beweisen, dass sie es kennen, und ein Webhook aus der Desktop-App hat immer eins (Webhook-Secret in seinen Einstellungen). Signiere den unveränderten Request-Body mit HMAC-SHA256 und dem Secret, und sende den Hex-Digest in Kleinbuchstaben im Header X-Mssgs-Signature als 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
});

Auch GitHubs eigener Header X-Hub-Signature-256 wird angenommen, ein GitHub-Webhook mit demselben Secret funktioniert also unverändert. Die Signatur hat keinen Zeitstempel und verhindert daher nicht, dass ein abgefangener Request noch einmal gesendet wird: Die URL bleibt das Geheimnis, auf das es ankommt.

Antworten und Fehler

Eine gepostete Nachricht kommt mit ihrer ID und einer callback_url zurück, mit der du sie 30 Minuten lang aktualisieren oder löschen kannst.

{
  "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}`);
}

Hat die Nachricht Buttons, enthält die Antwort außerdem eine stream_url: einen Live-Stream der Antworten, Reaktionen und Button-Drücke auf diese Nachricht, 10 Minuten lang offen, oder eine Stunde, wenn du "sse_event_extended_timeout": true mitsendest. Siehe Live-Updates.

Statuscodes

Fehlercodes

Dateifehler

Limits

Requests sind rate-limitiert. Bekommst du eine 429, warte, bevor du erneut sendest, und fass Alarme, die schubweise kommen, in einer Nachricht zusammen.

GitHub, UniFi und App Store Connect

Richte einen dieser Dienste auf eine Webhook-URL, und mssgs erkennt ihn und postet eine passende Karte, ohne dass du eine Payload schreiben musst. Siehe Integrationen. Diese Dienste bekommen {"success": true} als Antwort und keine Callback-URL.