Skelbk žinutes per webhook

Greita pradžia

1. 1

   Sukurk webhook

   Kompiuterio programėlėje atidaryk savo bendruomenės Manage Server → Webhooks, sukurk webhook, pasirink kanalus, kuriuose jis gali skelbti, ir nukopijuok kanalo URL. Jis atrodo taip:

   urlKopijuoti

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

2. 2

   Išsiųsk žinutę

   Pasirašyk JSON webhook’o slaptuoju raktu ir išsiųsk jį POST užklausa. Kompiuterio programėlėje sukurtas webhook visada turi slaptąjį raktą: nukopijuok jį iš Webhook Secret webhook’o nustatymuose.

   bashKopijuoti

   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

   Perskaityk atsakymą

   Atsakyme gausi žinutės id ir callback_url, kuriuo vėliau galėsi pakeisti žinutę.

   jsonKopijuoti

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

Ką gali siųsti

Žinutė yra arba trumpoji forma (tekstas su pavadinimu ir spalva), arba visa kortelė, ir abi gali turėti mygtukų bei failų. Kortelės viršuje visada rodomas paties webhook’o pavadinimas. Webhook’o nustatymuose taip pat nusprendi, ar jis gali skelbti paveikslėlius ir paminėti žmones.

Trumpoji forma

Pakanka daugumai įspėjimų.

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

Visa kortelė

Siųsk message_container, kad gautum kortelę su pavadinimu nuoroda, paantrašte, markdown, laukais ir paveikslėliais. Per webhook kortelė priima type, color, title, title_url, sub_title, description, fields, avatar_url, image_url, image_base64, images ir loader laukus. Būsenos ženkliukas, žymė, diff statistika ir suskleisti samprotavimai skirti atsakymams į komandas. Visi laukai aprašyti puslapyje žinučių kortelės.

jsonKopijuoti

{
  "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 sėkmingas

Visi 212 testų main šakoje praeina.

Duration

2m 34s

Commit

1a2b3c4

09:12

Mygtukai

Pridėk actions masyvą, kad po žinute atsirastų mygtukai. Kaip jie veikia, rasi puslapyje mygtukai.

Failai

Skelbk su žinute tikrus failus: žurnalą, ataskaitą, ekrano nuotrauką. Jie rodomi kaip bet kuris kitas priedas: kaip atsisiuntimo eilutė, o paveikslėliai, vaizdo ir garso įrašai tiesiai žinutėje. Žinutė vien su failais taip pat tinka: praleisk content ir kortelę.

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

Kodėl url priima tik mssgs adresus

Webhook URL dažnai atsiduria įklijuotas kitų paslaugų skydeliuose. Nutekėjęs URL neturi leisti kam nors priversti kiekvieno nario programėlės parsisiųsti failo iš jo pasirinkto serverio. Jei tavo failas yra kitur, siųsk jį kaip content_base64, ir mssgs jį talpins.

Nepavykęs įkėlimas nesustabdo žinutės

Failai patikrinami iš anksto, bet įkeliami vėliau. Jei įkėlimas nepavyksta, tas failas praleidžiamas, o likusi žinutė vis tiek paskelbiama, be klaidos: geriau prarasti failą nei ataskaitą. Jei failas svarbus, patikrink, ar jis atkeliavo.

Failas iš komandinės eilutės

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

Užklausų pasirašymas

Webhook su slaptuoju raktu priima tik tas užklausas, kurios įrodo, kad jį žino, o kompiuterio programėlėje sukurtas webhook visada jį turi (Webhook Secret jo nustatymuose). Pasirašyk neapdorotą užklausos turinį HMAC-SHA256 algoritmu naudodamas slaptąjį raktą ir siųsk mažosiomis raidėmis užrašytą hex santrauką antraštėje X-Mssgs-Signature kaip 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
});

Priimama ir paties GitHub antraštė X-Hub-Signature-256, todėl GitHub webhook su tuo pačiu slaptuoju raktu veikia be pakeitimų. Parašas neturi laiko žymos, todėl neapsaugo nuo to, kad perimta užklausa būtų išsiųsta dar kartą: svarbiausia paslaptis lieka pats URL.

Atsakymai ir klaidos

Paskelbta žinutė grąžinama su savo id ir callback_url, kuriuo 30 minučių gali ją atnaujinti ar ištrinti.

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

Kai žinutėje yra mygtukų, atsakyme taip pat yra stream_url: gyvas tos žinutės atsakymų, reakcijų ir mygtukų paspaudimų srautas, atviras 10 minučių arba valandą, jei siunti "sse_event_extended_timeout": true. Žr. atnaujinimai realiuoju laiku.

Būsenos kodai

Klaidų kodai

Failų klaidos

Limitai

Užklausų dažnis ribojamas. Gavęs 429, palauk prieš siųsdamas vėl, o pliūpsniais ateinančius įspėjimus sujunk į vieną žinutę.

GitHub, UniFi ir App Store Connect

Nukreipk vieną iš šių paslaugų į webhook URL, ir mssgs ją atpažins bei paskelbs tvarkingą kortelę, nereikės rašyti jokio payload. Žr. integracijos. Šios paslaugos atsakymu gauna {"success": true} ir jokio callback URL.