Objavljuj poruke webhookom

Brzi početak

1. 1

   Izradi webhook

   U aplikaciji za računalo otvori u svojoj zajednici Manage Server → Webhooks, izradi webhook, odaberi kanale u kojima smije objavljivati i kopiraj URL za kanal. Izgleda ovako:

   urlKopiraj

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

2. 2

   Pošalji poruku

   Potpiši JSON tajnim ključem webhooka i pošalji ga POST zahtjevom. Webhook izrađen u aplikaciji za računalo uvijek ga ima: kopiraj ga iz polja Webhook Secret u postavkama 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

   Pročitaj odgovor

   Odgovor ti daje id poruke i callback_url kojim kasnije možeš promijeniti poruku.

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

Što možeš poslati

Poruka je ili kratki oblik (tekst s naslovom i bojom) ili puna kartica, a oba mogu nositi gumbe i datoteke. Ime na vrhu kartice uvijek je ime samog webhooka. U postavkama webhooka odlučuješ i smije li objavljivati slike i spominjati ljude.

Kratki oblik

Dovoljan za većinu upozorenja.

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

Puna kartica

Pošalji message_container za karticu s naslovom koji je poveznica, podnaslovom, markdownom, poljima i slikama. Kroz webhook kartica prima type, color, title, title_url, sub_title, description, fields, avatar_url, image_url, image_base64, images i polja loadera. Oznaka statusa, značka, statistika diffa i sklopljeno razmišljanje namijenjeni su odgovorima na naredbe. Sva polja opisuje stranica kartice poruka.

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 prošao

Svih 212 testova prolazi na main.

Duration

2m 34s

Commit

1a2b3c4

09:12

Gumbi

Dodaj niz actions i ispod poruke pojavit će se gumbi. Kako rade, opisuje stranica gumbi.

Datoteke

Uz poruku objavi prave datoteke: log, izvještaj, snimku zaslona. Prikazuju se kao svaki drugi privitak, kao redak za preuzimanje, a slike, video i zvuk izravno u poruci. Poruka samo s datotekama sasvim je u redu: izostavi content i karticu.

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

Zašto url prima samo mssgs adrese

URL webhooka često završi zalijepljen u nadzorne ploče drugih usluga. Ako procuri, nitko ga ne smije moći iskoristiti da aplikacija svakog člana preuzme datoteku sa servera koji je sam odabrao. Ako je tvoja datoteka negdje drugdje, pošalji je kao content_base64 i mssgs će je hostati.

Neuspjeli prijenos datoteke ne ruši poruku

Datoteke se provjeravaju unaprijed, ali se prenose naknadno. Ako prijenos ne uspije, ta datoteka izostaje, a ostatak poruke ipak se objavi, bez pogreške: bolje izgubiti datoteku nego izvještaj. Ako ti je datoteka važna, provjeri je li stigla.

Datoteka iz naredbenog retka

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

Potpisivanje zahtjeva

Webhook s tajnim ključem prihvaća samo zahtjeve koji dokazuju da ga znaju, a webhook izrađen u aplikaciji za računalo uvijek ga ima (Webhook Secret u njegovim postavkama). Potpiši sirovo tijelo zahtjeva algoritmom HMAC-SHA256 pomoću tajnog ključa i pošalji heksadecimalni sažetak malim slovima u zaglavlju X-Mssgs-Signature kao 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
});

Prihvaća se i GitHubovo vlastito zaglavlje X-Hub-Signature-256, pa GitHub webhook s istim tajnim ključem radi bez izmjena. Potpis nema vremensku oznaku, pa ne sprječava ponovno slanje presretnutog zahtjeva: tajna koja se zaista računa ostaje URL.

Odgovori i pogreške

Objavljena poruka vraća se sa svojim id-jem i callback_url kojim je 30 minuta možeš ažurirati ili izbrisati.

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

Kad poruka ima gumbe, odgovor sadrži i stream_url: stream uživo s odgovorima, reakcijama i pritiscima gumba na toj poruci, otvoren 10 minuta, ili sat vremena ako pošalješ "sse_event_extended_timeout": true. Pogledaj ažuriranja uživo.

Statusni kodovi

Kodovi pogrešaka

Pogreške s datotekama

Ograničenja

Zahtjevi imaju ograničenje učestalosti. Kad dobiješ 429, pričekaj prije ponovnog slanja, a upozorenja koja stižu u naletima spoji u jednu poruku.

GitHub, UniFi i App Store Connect

Usmjeri jednu od ovih usluga na URL webhooka i mssgs će je prepoznati i objaviti urednu karticu, bez pisanja payloada. Pogledaj integracije. Te usluge u odgovoru dobivaju {"success": true} i nikakav callback URL.