Objavljaj sporočila z webhookom

Hiter začetek

1. 1

   Ustvari webhook

   V namizni aplikaciji v svoji skupnosti odpri Manage Server → Webhooks, ustvari webhook, izberi kanale, v katerih sme objavljati, in kopiraj URL za kanal. Ima to obliko:

   urlKopiraj

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

2. 2

   Pošlji sporočilo

   JSON podpiši s skrivnim ključem webhooka in ga pošlji z zahtevo POST. Webhook, ustvarjen v namizni aplikaciji, ga ima vedno: kopiraj ga iz polja Webhook Secret v nastavitvah webhooka.

   bashKopiraj

   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

   Preberi odgovor

   Odgovor vsebuje ID sporočila in callback_url, s katerim sporočilo pozneje spremeniš.

   jsonKopiraj

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

Kaj lahko pošlješ

Sporočilo je bodisi kratka oblika (besedilo z naslovom in barvo) bodisi cela kartica, obe pa lahko vsebujeta gumbe in datoteke. Ime na vrhu kartice je vedno ime samega webhooka. V nastavitvah webhooka določiš tudi, ali sme objavljati slike in omenjati ljudi.

Kratka oblika

Dovolj za večino opozoril.

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

Cela kartica

Pošlji message_container za kartico z naslovom kot povezavo, podnaslovom, markdownom, polji in slikami. Prek webhooka kartica sprejme type, color, title, title_url, sub_title, description, fields, avatar_url, image_url, image_base64, images in polja za indikator nalaganja. Oznaka stanja, značka, statistika sprememb in skrito razmišljanje so namenjeni odgovorom na ukaze. Vsa polja so opisana na strani kartice sporočil.

jsonKopiraj

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

Vseh 212 testov na main je zelenih.

Duration

2m 34s

Commit

1a2b3c4

09:12

Gumbi

Dodaj seznam actions in pod sporočilom se prikažejo gumbi. Kako delujejo, piše na strani gumbi.

Datoteke

S sporočilom objavi prave datoteke: dnevnik, poročilo, posnetek zaslona. Prikažejo se kot vsaka druga priponka, kot vrstica za prenos, slike, video in zvok pa neposredno v sporočilu. Tudi sporočilo samo z datotekami je v redu: izpusti content in kartico.

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

Zakaj url sprejema samo naslove mssgs

URL webhooka pogosto pristane prilepljen v druge nadzorne plošče. Če uide v javnost, ne sme nikomur omogočiti, da bi aplikacija vsakega člana prenesla datoteko s strežnika po njegovi izbiri. Če je tvoja datoteka drugje, jo pošlji kot content_base64 in mssgs jo bo gostil.

Neuspešno nalaganje datoteke ne ustavi sporočila

Datoteke se preverijo vnaprej, naložijo pa pozneje. Če nalaganje spodleti, ta datoteka izpade, preostanek sporočila pa se vseeno objavi, brez napake: bolje izgubiti datoteko kot poročilo. Če je datoteka pomembna, preveri, ali je prispela.

Datoteka iz ukazne vrstice

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

Podpisovanje zahtev

Webhook s skrivnim ključem sprejme le zahteve, ki dokažejo, da ga poznajo, webhook, ustvarjen v namizni aplikaciji, pa ga ima vedno (Webhook Secret v njegovih nastavitvah). Surovo telo zahteve podpiši s HMAC-SHA256 in skrivnim ključem, šestnajstiški povzetek z malimi črkami pa pošlji v glavi X-Mssgs-Signature kot 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
});

Sprejeta je tudi GitHubova glava X-Hub-Signature-256, zato webhook na GitHubu z istim skrivnim ključem deluje brez sprememb. Podpis nima časovnega žiga, zato ne prepreči ponovnega pošiljanja prestrežene zahteve: skrivnost, ki res šteje, ostaja URL.

Odgovori in napake

Objavljeno sporočilo se vrne s svojim ID-jem in callback_url, s katerim ga lahko 30 minut posodabljaš ali ga izbrišeš.

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

Če ima sporočilo gumbe, odgovor vsebuje tudi stream_url: tok v živo z odgovori, reakcijami in pritiski gumbov na tem sporočilu, odprt 10 minut ali eno uro, če pošlješ "sse_event_extended_timeout": true. Glej posodobitve v živo.

Statusne kode

Kode napak

Napake pri datotekah

Omejitve

Število zahtev je omejeno. Ko dobiš 429, počakaj, preden znova pošlješ, opozorila, ki prihajajo v valovih, pa združi v eno sporočilo.

GitHub, UniFi in App Store Connect

Usmeri eno od teh storitev na URL webhooka in mssgs jo prepozna ter objavi pravo kartico, ne da bi ti moral pisati payload. Glej integracije. Te storitve dobijo odgovor {"success": true} brez callback URL-ja.