Üzenetküldés webhookkal

Gyors kezdés

1. 1

   Hozd létre a webhookot

   Az asztali alkalmazásban nyisd meg a közösséged Manage Server → Webhooks menüpontját, hozz létre egy webhookot, válaszd ki, mely csatornákba küldhet üzenetet, és másold ki egy csatorna URL-jét. Így néz ki:

   urlMásolás

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

2. 2

   Küldj egy üzenetet

   Írd alá a JSON-t a webhook titkos kulcsával, és küldd el POST-kéréssel. Az asztali alkalmazásban létrehozott webhooknak mindig van ilyen kulcsa: másold ki a webhook beállításainak Webhook Secret mezőjéből.

   bashMásolás

   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

   Olvasd el a választ

   A válaszban megkapod az üzenet azonosítóját, és egy callback_url címet, amellyel később módosíthatod az üzenetet.

   jsonMásolás

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

Mit küldhetsz

Egy üzenet vagy rövid formájú (szöveg címmel és színnel), vagy teljes kártya, és mindkettő tartalmazhat gombokat és fájlokat. A kártya tetején mindig a webhook saját neve áll. A webhook beállításaiban azt is eldöntöd, hogy küldhet-e képeket, és megemlíthet-e másokat.

Rövid forma

A legtöbb riasztáshoz elég.

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

Teljes kártya

Küldj egy message_container objektumot, ha linkelt címmel, alcímmel, markdownnal, mezőkkel és képekkel ellátott kártyát szeretnél. Webhookon keresztül a kártya ezeket a mezőket fogadja: type, color, title, title_url, sub_title, description, fields, avatar_url, image_url, image_base64, images, valamint a betöltésjelző mezői. A státuszcímke, a jelvény, a diff-statisztika és az összecsukott gondolatmenet a parancsokra adott válaszokhoz való. Minden mező leírása az üzenetkártyák oldalon található.

jsonMásolás

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

Mind a 212 teszt zöld a main ágon.

Duration

2m 34s

Commit

1a2b3c4

09:12

Gombok

Egy actions tömbbel gombokat tehetsz az üzenet alá. A működésüket a gombok oldal írja le.

Fájlok

Küldj valódi fájlokat az üzenettel: naplót, jelentést, képernyőképet. Ugyanúgy jelennek meg, mint bármely más melléklet: letöltési sorként, a képek, videók és hangfájlok pedig közvetlenül az üzenetben. Csak fájlokat tartalmazó üzenet is küldhető: hagyd el a content mezőt és a kártyát.

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

Miért fogad el az url csak mssgs-címeket

A webhook URL-je gyakran más irányítópultokra is bekerül. Ha kiszivárog, akkor sem szabad, hogy bárki rávehesse vele minden tag alkalmazását arra, hogy egy általa választott szerverről töltsön le fájlt. Ha a fájlod máshol van, küldd el a content_base64 mezőben, és az mssgs tárolja.

A sikertelen feltöltés nem buktatja el az üzenetet

A fájlokat a rendszer előre ellenőrzi, de csak utána tölti fel. Ha egy feltöltés nem sikerül, az a fájl kimarad, az üzenet többi része pedig hiba nélkül megjelenik: jobb elveszíteni a fájlt, mint a jelentést. Ha egy fájl fontos, ellenőrizd, hogy megérkezett-e.

Fájl küldése parancssorból

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

Kérések aláírása

A titkos kulccsal rendelkező webhook csak olyan kéréseket fogad el, amelyek igazolják, hogy ismerik a kulcsot, és az asztali alkalmazásban létrehozott webhooknak mindig van ilyen (Webhook Secret a beállításaiban). Írd alá a nyers kéréstörzset HMAC-SHA256-tal a titkos kulcs használatával, és küldd el a kisbetűs hex digestet az X-Mssgs-Signature fejlécben, sha256=<hex> formában.

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
});

A GitHub saját X-Hub-Signature-256 fejlécét is elfogadjuk, így egy ugyanazzal a titkos kulccsal beállított GitHub-webhook változtatás nélkül működik. Az aláírás nem tartalmaz időbélyeget, ezért nem akadályozza meg, hogy egy elfogott kérést újra elküldjenek: a valódi titok továbbra is az URL.

Válaszok és hibák

A sikeresen elküldött üzenet visszaadja az azonosítóját és egy callback_url címet, amellyel 30 percig frissítheted vagy törölheted.

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

Ha az üzenetnek vannak gombjai, a válaszban egy stream_url is szerepel: az üzenetre érkező válaszok, reakciók és gombnyomások élő streamje, amely 10 percig marad nyitva, vagy egy óráig, ha "sse_event_extended_timeout": true értéket küldesz. Lásd: élő frissítések.

Státuszkódok

Hibakódok

Fájlhibák

Korlátok

A kérések gyakorisága korlátozott. Ha 429 választ kapsz, várj, mielőtt újra küldenél, és a hullámokban érkező riasztásokat fogd össze egyetlen üzenetbe.

GitHub, UniFi és App Store Connect

Irányítsd valamelyik szolgáltatást egy webhook URL-re, és az mssgs felismeri, majd rendes kártyát küld be, payload írása nélkül. Lásd: integrációk. Ezek {"success": true} választ kapnak, callback URL nélkül.