Posielaj správy cez webhook

Rýchly štart

1. 1

   Vytvor webhook

   V desktopovej aplikácii otvor vo svojej komunite Manage Server → Webhooks, vytvor webhook, vyber kanály, do ktorých môže posielať, a skopíruj URL pre kanál. Vyzerá takto:

   urlKopírovať

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

2. 2

   Pošli správu

   Podpíš JSON tajným kľúčom webhooku a pošli ho cez POST. Webhook vytvorený v desktopovej aplikácii ho má vždy: skopíruj ho z poľa Webhook Secret v nastaveniach webhooku.

   bashKopírovať

   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

   Prečítaj odpoveď

   Odpoveď obsahuje id správy a callback_url, cez ktorú správu neskôr zmeníš.

   jsonKopírovať

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

Čo môžeš poslať

Správa je buď krátka forma (text s nadpisom a farbou), alebo plná karta, a obe môžu niesť tlačidlá a súbory. Meno navrchu karty je vždy vlastný názov webhooku. V nastaveniach webhooku tiež rozhodneš, či smie posielať obrázky a zmieňovať ľudí.

Krátka forma

Na väčšinu upozornení stačí.

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

Plná karta

Pošli message_container a dostaneš kartu s nadpisom ako odkazom, podnadpisom, markdownom, poľami a obrázkami. Cez webhook karta prijíma type, color, title, title_url, sub_title, description, fields, avatar_url, image_url, image_base64, images a polia loadera. Stavový štítok, odznak, štatistiky diffu a zbalené uvažovanie patria odpovediam na príkazy. Všetky polia nájdeš na stránke karty správ.

jsonKopírovať

{
  "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 prešiel

Všetkých 212 testov na main je zelených.

Duration

2m 34s

Commit

1a2b3c4

09:12

Tlačidlá

Pridaj pole actions a pod správou sa objavia tlačidlá. Ako fungujú, sa dočítaš na stránke tlačidlá.

Súbory

Pošli so správou skutočné súbory: log, report, snímku obrazovky. Zobrazia sa ako každá iná príloha, ako riadok na stiahnutie, obrázky, video a zvuk priamo v správe. Správa iba so súbormi je v poriadku: vynechaj content aj kartu.

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

Prečo url prijíma iba adresy mssgs

URL webhooku často skončí vložená v iných dashboardoch. Ak unikne, nesmie nikomu umožniť, aby aplikácia každého člena sťahovala súbor zo servera, ktorý si ten človek vybral. Ak je tvoj súbor inde, pošli ho ako content_base64 a mssgs ho bude hostovať.

Neúspešné nahratie súboru nezhodí správu

Súbory sa skontrolujú vopred, ale nahrajú sa až potom. Ak nahratie zlyhá, ten súbor sa vynechá a zvyšok správy sa aj tak pošle, bez chyby: lepšie prísť o súbor ako o report. Ak na súbore záleží, over si, že dorazil.

Súbor z príkazového riadka

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

Podpisovanie požiadaviek

Webhook s tajným kľúčom prijme iba požiadavky, ktoré dokážu, že ho poznajú, a webhook vytvorený v desktopovej aplikácii ho má vždy (Webhook Secret v jeho nastaveniach). Podpíš surové telo požiadavky algoritmom HMAC-SHA256 s tajným kľúčom a pošli hexadecimálny digest malými písmenami v hlavičke X-Mssgs-Signature ako 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
});

Prijíma sa aj vlastná hlavička GitHubu X-Hub-Signature-256, takže webhook z GitHubu s rovnakým tajným kľúčom funguje bez úprav. Podpis neobsahuje časovú pečiatku, takže nezabráni opätovnému odoslaniu zachytenej požiadavky: tajomstvom, na ktorom naozaj záleží, zostáva URL.

Odpovede a chyby

Odoslaná správa sa vráti so svojím id a callback_url, cez ktorú ju počas 30 minút môžeš aktualizovať alebo zmazať.

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

Keď má správa tlačidlá, odpoveď obsahuje aj stream_url: živý stream odpovedí, reakcií a stlačení tlačidiel na tej správe, otvorený 10 minút, alebo hodinu, keď pošleš "sse_event_extended_timeout": true. Pozri živé aktualizácie.

Stavové kódy

Chybové kódy

Chyby súborov

Limity

Počet požiadaviek je obmedzený. Keď dostaneš 429, pred ďalším odoslaním počkaj a upozornenia, ktoré prichádzajú v nárazoch, zlúč do jednej správy.

GitHub, UniFi a App Store Connect

Nasmeruj niektorú z týchto služieb na URL webhooku a mssgs ju rozpozná a pošle poriadnu kartu, payload písať netreba. Pozri integrácie. Tieto služby dostanú odpoveď {"success": true} a žiadnu callback URL.