Publicē ziņas ar webhook

Ātrais sākums

1. 1

   Izveido webhook

   Datora lietotnē atver savas kopienas Manage Server → Webhooks, izveido webhook, izvēlies kanālus, kuros tas drīkst publicēt, un nokopē kanāla URL. Tas izskatās šādi:

   urlKopēt

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

2. 2

   Nosūti ziņu

   Paraksti JSON ar webhook slepeno atslēgu un nosūti to ar POST. Datora lietotnē izveidotam webhook tā ir vienmēr: nokopē to no lauka Webhook Secret webhook iestatījumos.

   bashKopēt

   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

   Izlasi atbildi

   Atbildē ir ziņas id un callback_url, ar kuru ziņu vēlāk var mainīt.

   jsonKopēt

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

Ko var nosūtīt

Ziņa ir vai nu īsā forma (teksts ar virsrakstu un krāsu), vai pilna kartīte, un abām var būt pogas un faili. Nosaukums kartītes augšā vienmēr ir paša webhook nosaukums. Webhook iestatījumos tu arī nosaki, vai tas drīkst publicēt attēlus un pieminēt cilvēkus.

Īsā forma

Pietiek lielākajai daļai brīdinājumu.

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

Pilna kartīte

Nosūti message_container, lai iegūtu kartīti ar virsrakstu kā saiti, apakšvirsrakstu, markdown, laukiem un attēliem. Caur webhook kartīte pieņem type, color, title, title_url, sub_title, description, fields, avatar_url, image_url, image_base64, images un ielādes indikatora laukus. Statusa birka, nozīmīte, diff statistika un sakļautā spriešana ir paredzēta komandu atbildēm. Visi lauki ir aprakstīti lapā ziņu kartītes.

jsonKopēt

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

Būvējums #1847 izdevās

Visi 212 testi uz main ir zaļi.

Duration

2m 34s

Commit

1a2b3c4

09:12

Pogas

Pievieno masīvu actions, lai zem ziņas būtu pogas. Kā tās darbojas, skaidrots lapā pogas.

Faili

Publicē kopā ar ziņu īstus failus: žurnālu, atskaiti, ekrānuzņēmumu. Tie izskatās kā jebkurš cits pielikums: kā lejupielādes rinda, bet attēli, video un audio tieši ziņā. Ziņa tikai ar failiem arī der: izlaid content un kartīti.

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

Kāpēc url pieņem tikai mssgs adreses

Webhook URL bieži nonāk citu servisu paneļos. Ja tas noplūst, nevienam nedrīkst rasties iespēja likt katra dalībnieka lietotnei ielādēt failu no paša izvēlēta servera. Ja tavs fails atrodas citur, nosūti to kā content_base64, un mssgs to mitinās.

Neizdevusies augšupielāde neaptur ziņu

Faili tiek pārbaudīti uzreiz, bet augšupielādēti pēc tam. Ja augšupielāde neizdodas, šis fails tiek izlaists, bet pārējā ziņa tik un tā tiek publicēta, bez kļūdas: labāk zaudēt failu nekā atskaiti. Ja fails ir svarīgs, pārbaudi, vai tas ir pienācis.

Fails no komandrindas

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

Pieprasījumu parakstīšana

Webhook ar slepeno atslēgu pieņem tikai pieprasījumus, kas pierāda, ka to zina, un datora lietotnē izveidotam webhook tā ir vienmēr (Webhook Secret tā iestatījumos). Paraksti pieprasījuma neapstrādāto body ar HMAC-SHA256, izmantojot slepeno atslēgu, un nosūti heksadecimālo digest mazajiem burtiem galvenē X-Mssgs-Signature formā 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
});

Tiek pieņemta arī GitHub paša galvene X-Hub-Signature-256, tāpēc GitHub webhook ar to pašu slepeno atslēgu darbojas bez izmaiņām. Parakstā nav laika zīmoga, tāpēc tas neliedz pārtvertu pieprasījumu nosūtīt vēlreiz: svarīgākais noslēpums joprojām ir URL.

Atbildes un kļūdas

Publicēta ziņa atgriežas ar savu id un callback_url, ar kuru to 30 minūtes var atjaunināt vai dzēst.

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

Ja ziņai ir pogas, atbildē ir arī stream_url: reāllaika plūsma ar atbildēm, reakcijām un pogu nospiešanām uz šīs ziņas, atvērta 10 minūtes vai stundu, ja nosūti "sse_event_extended_timeout": true. Skati atjauninājumus reāllaikā.

Statusa kodi

Kļūdu kodi

Failu kļūdas

Limiti

Pieprasījumu biežums ir ierobežots. Ja saņem 429, pagaidi, pirms sūti vēlreiz, un brīdinājumus, kas pienāk viļņveidā, apvieno vienā ziņā.

GitHub, UniFi un App Store Connect

Norādi kādam no šiem servisiem webhook URL, un mssgs to atpazīs un publicēs kārtīgu kartīti, bez paša rakstīta payload. Skati integrācijas. Šie servisi saņem atbildi {"success": true} bez callback URL.