Post beskeder med en webhook

Kom godt i gang

1. 1

   Opret webhooken

   Åbn Administrer fællesskab → Webhooks for dit fællesskab i desktop-appen, opret en webhook, vælg de kanaler, den må poste i, og kopiér URL'en til en kanal. Den ser sådan ud:

   urlKopiér

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

2. 2

   Send en besked

   Signér JSON'en med webhookens hemmelighed, og send den med POST. En webhook, du opretter i skrivebordsappen, har altid en: kopiér den under Webhook-hemmelighed i webhookens indstillinger.

   bashKopiér

   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

   Læs svaret

   Svaret giver dig beskedens id og en callback_url, så du kan ændre beskeden senere.

   jsonKopiér

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

Det kan du sende

En besked er enten den korte form (tekst med en titel og en farve) eller et helt kort, og begge kan have knapper og filer. Navnet øverst på kortet er altid webhookens eget navn. I webhookens indstillinger bestemmer du også, om den må poste billeder og omtale folk.

Kort form

Nok til de fleste advarsler.

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

Et helt kort

Send en message_container for et kort med en titel som link, en undertitel, markdown, felter og billeder. Gennem en webhook tager et kort type, color, title, title_url, sub_title, description, fields, avatar_url, image_url, image_base64, images og loader-felterne. Statuspillen, mærket, diff-statistikken og den sammenfoldede tænkning er til kommandosvar. Alle felter står under beskedkort.

jsonKopiér

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

Besked fra CI

Build #1847 bestået

Alle 212 tests er grønne på main.

Duration

2m 34s

Commit

1a2b3c4

09:12

Knapper

Tilføj et actions-array for at sætte knapper under beskeden. Hvordan de virker, står under knapper.

Filer

Post rigtige filer med en besked: en log, en rapport, et skærmbillede. De vises som alle andre vedhæftede filer, som en række, der kan downloades, eller inline for billeder, video og lyd. En besked med kun filer er fin: udelad content og kortet.

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

Hvorfor url kun tager mssgs-adresser

En webhook-URL ender ofte med at blive indsat i andre dashboards. En lækket URL må ikke kunne bruges til at få alle medlemmers app til at hente en fil fra en server, som afsenderen selv har valgt. Ligger din fil et andet sted, så send den som content_base64, så hoster mssgs den.

En mislykket upload stopper ikke beskeden

Filer tjekkes på forhånd, men uploades bagefter. Fejler en upload, udelades den fil, og resten af beskeden bliver stadig postet, uden en fejl: det er bedre at miste filen end at miste rapporten. Er en fil vigtig, så tjek, at den kom frem.

En fil fra kommandolinjen

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

Signering af requests

En webhook med en hemmelighed accepterer kun requests, der beviser, at de kender den, og en webhook, du opretter i skrivebordsappen, har altid en (Webhook-hemmelighed i dens indstillinger). Signér den rå request-body med HMAC-SHA256 og hemmeligheden, og send det hexadecimale digest med små bogstaver i headeren X-Mssgs-Signature som 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
});

GitHubs egen header X-Hub-Signature-256 accepteres også, så en GitHub-webhook med den samme hemmelighed virker, som den er. Signaturen har intet tidsstempel, så den forhindrer ikke, at en opsnappet request bliver sendt igen: det er stadig URL'en, der er hemmeligheden, der betyder noget.

Svar og fejl

En besked, der blev postet, kommer tilbage med sit id og en callback_url, som du kan opdatere eller slette den med i 30 minutter.

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

Har beskeden knapper, indeholder svaret også en stream_url: en live stream af svar, reaktioner og tryk på knapper på den besked, åben i 10 minutter, eller en time, når du sender "sse_event_extended_timeout": true. Se liveopdateringer.

Statuskoder

Fejlkoder

Filfejl

Grænser

Requests er rate-begrænsede. Får du en 429, så vent, før du sender igen, og saml advarsler, der kommer i ryk, i én besked.

GitHub, UniFi og App Store Connect

Peg en af disse tjenester mod en webhook-URL, så genkender mssgs den og poster et ordentligt kort, uden at du skal skrive en payload. Se integrationer. De får {"success": true} som svar og ingen callback-URL.