Berichten posten met een webhook

Snel aan de slag

1. 1

   Maak de webhook aan

   Open in de desktop-app bij je community Server beheren → Webhooks, maak een webhook aan, kies de kanalen waarin hij mag posten en kopieer de URL voor een kanaal. Die ziet er zo uit:

   urlKopieer

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

2. 2

   Stuur een bericht

   Onderteken de JSON met het secret van de webhook en POST hem. Een webhook die je in de desktop-app maakt, heeft er altijd een: kopieer hem bij Webhook Secret in de instellingen van de webhook.

   bashKopieer

   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

   Lees het antwoord

   Het antwoord geeft je het bericht-id, en een callback_url om het bericht later aan te passen.

   jsonKopieer

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

Wat je kunt sturen

Een bericht is de korte vorm (tekst met een titel en een kleur) of een volledige kaart, en allebei kunnen ze knoppen en bestanden meekrijgen. De naam bovenaan de kaart is altijd de eigen naam van de webhook. In de instellingen van de webhook bepaal je ook of hij afbeeldingen mag posten en mensen mag noemen.

Korte vorm

Genoeg voor de meeste meldingen.

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

Een volledige kaart

Stuur een message_container voor een kaart met een gelinkte titel, een subtitel, markdown, velden en afbeeldingen. Via een webhook kent een kaart type, color, title, title_url, sub_title, description, fields, avatar_url, image_url, image_base64, images en de loadervelden. De statuspill, de badge, de diff-stats en de ingeklapte redenering zijn voor antwoorden op commando's. Elk veld staat bij berichtkaarten.

jsonKopieer

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

Bericht van CI

Build #1847 geslaagd

Alle 212 tests groen op main.

Duration

2m 34s

Commit

1a2b3c4

09:12

Knoppen

Voeg een actions-array toe om knoppen onder het bericht te zetten. Hoe ze werken lees je bij knoppen.

Bestanden

Post echte bestanden bij een bericht: een log, een rapport, een screenshot. Ze verschijnen zoals elke andere bijlage, als downloadregel of, bij afbeeldingen, video en audio, direct in het bericht. Een bericht met alleen bestanden mag ook: laat content en de kaart 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"
    }
  ]
}

Waarom url alleen mssgs-adressen accepteert

Een webhook-URL wordt vaak in andere dashboards geplakt. Een gelekte URL mag iemand niet de kans geven om de app van elk lid een bestand te laten ophalen van een server die hij zelf kiest. Staat je bestand ergens anders, stuur het dan als content_base64 en mssgs host het voor je.

Een mislukte upload laat het bericht niet mislukken

Bestanden worden vooraf gecontroleerd, maar pas daarna geüpload. Mislukt een upload, dan valt dat bestand weg en wordt de rest van het bericht gewoon gepost, zonder foutmelding: het bestand kwijtraken is beter dan het hele rapport kwijtraken. Is een bestand belangrijk, controleer dan of het is aangekomen.

Een bestand vanaf de commandline

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 ondertekenen

Een webhook met een secret accepteert alleen requests die bewijzen dat ze dat secret kennen, en een webhook die je in de desktop-app maakt, heeft er altijd een (Webhook Secret in zijn instellingen). Onderteken de ruwe request body met HMAC-SHA256 en het secret, en stuur de hex-digest in kleine letters mee in de 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
});

De eigen header X-Hub-Signature-256 van GitHub wordt ook geaccepteerd, dus een GitHub-webhook met hetzelfde secret werkt meteen. De handtekening bevat geen tijdstempel en houdt dus niet tegen dat een onderschept request opnieuw wordt verstuurd: de URL blijft het geheim waar het om draait.

Antwoorden en fouten

Een bericht dat is gepost, komt terug met zijn id en een callback_url om het 30 minuten lang bij te werken of te verwijderen.

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

Heeft het bericht knoppen, dan bevat het antwoord ook een stream_url: een live stream van de antwoorden, reacties en knopdrukken op dat bericht, 10 minuten open, of een uur als je "sse_event_extended_timeout": true meestuurt. Zie live-updates.

Statuscodes

Foutcodes

Fouten bij bestanden

Limieten

Requests hebben een rate limit. Krijg je een 429, wacht dan voordat je opnieuw stuurt, en bundel meldingen die in golven binnenkomen tot één bericht.

GitHub, UniFi en App Store Connect

Wijs een van deze services naar een webhook-URL en mssgs herkent hem en post een nette kaart, zonder dat je zelf een payload hoeft te schrijven. Zie integraties. Deze antwoorden met {"success": true} en zonder callback-URL.