Postita sõnumeid webhookiga

Kiirstart

1. 1

   Loo webhook

   Ava arvutirakenduses oma kogukonna Manage Server → Webhooks, loo webhook, vali kanalid, kuhu see tohib postitada, ja kopeeri kanali URL. See näeb välja selline:

   urlKopeeri

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

2. 2

   Saada sõnum

   Allkirjasta JSON webhooki secretiga ja saada see POST-päringuga. Arvutirakenduses loodud webhookil on secret alati olemas: kopeeri see webhooki seadetest väljalt Webhook Secret.

   bashKopeeri

   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

   Loe vastust

   Vastusest saad sõnumi id ja aadressi callback_url, millega sõnumit hiljem muuta.

   jsonKopeeri

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

Mida saad saata

Sõnum on kas lühivormis (tekst pealkirja ja värviga) või täielik kaart ning kumbki võib kanda nuppe ja faile. Kaardi ülaosas on alati webhooki enda nimi. Webhooki seadetes otsustad ka, kas see tohib postitada pilte ja inimesi mainida.

Lühivorm

Enamiku hoiatuste jaoks piisab sellest.

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

Täielik kaart

Saada message_container, et saada kaart lingitud pealkirja, alapealkirja, markdowni, väljade ja piltidega. Webhooki kaudu võtab kaart vastu väljad type, color, title, title_url, sub_title, description, fields, avatar_url, image_url, image_base64, images ja laadija väljad. Olekusilt, märk, diff-statistika ja kokkuvolditud arutluskäik on käskude vastuste jaoks. Kõik väljad leiad lehelt sõnumikaardid.

jsonKopeeri

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

Kõik 212 testi on harus main rohelised.

Duration

2m 34s

Commit

1a2b3c4

09:12

Nupud

Lisa massiiv actions, et panna nupud sõnumi alla. Kuidas need töötavad, loe lehelt nupud.

Failid

Postita sõnumiga päris faile: logi, raport, ekraanipilt. Need paistavad nagu iga teine manus, allalaadimisreana või piltide, video ja heli puhul otse sõnumis. Ka ainult failidega sõnum sobib: jäta content ja kaart ära.

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

Miks url võtab vastu ainult mssgs’i aadresse

Webhooki URL satub sageli teiste teenuste juhtpaneelidele. Lekkinud URL ei tohi lasta kellelgi panna iga liikme rakendust faili tooma serverist, mille tema valis. Kui sinu fail asub mujal, saada see väljana content_base64 ja mssgs majutab selle.

Ebaõnnestunud üleslaadimine ei nurjata sõnumit

Failid kontrollitakse kohe, aga laaditakse üles hiljem. Kui üleslaadimine ebaõnnestub, jäetakse see fail välja ja ülejäänud sõnum postitatakse ikkagi, ilma veata: parem kaotada fail kui raport. Kui fail on oluline, kontrolli, et see kohale jõudis.

Fail käsurealt

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

Päringute allkirjastamine

Secretiga webhook võtab vastu ainult päringuid, mis tõestavad, et teavad seda, ja arvutirakenduses loodud webhookil on secret alati olemas (Webhook Secret selle seadetes). Allkirjasta toores päringukeha secreti abil algoritmiga HMAC-SHA256 ja saada väiketähtedega hex-räsi päises X-Mssgs-Signature kujul 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
});

Vastu võetakse ka GitHubi enda päis X-Hub-Signature-256, nii et sama secretiga GitHubi webhook töötab muutmata kujul. Allkirjas pole ajatemplit, nii et see ei takista kinni püütud päringu uuesti saatmist: tegelik saladus on endiselt URL.

Vastused ja vead

Postitatud sõnum tuleb tagasi koos oma id ja aadressiga callback_url, millega saad seda 30 minuti jooksul uuendada või kustutada.

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

Kui sõnumil on nupud, on vastuses ka stream_url: selle sõnumi vastuste, reaktsioonide ja nupuvajutuste reaalajas voog, mis on avatud 10 minutit või tund, kui saadad "sse_event_extended_timeout": true. Vaata lehte reaalajas uuendused.

Olekukoodid

Veakoodid

Failivead

Piirangud

Päringute sagedus on piiratud. Kui saad vastuseks 429, oota enne uuesti saatmist ja koonda hooga saabuvad hoiatused üheks sõnumiks.

GitHub, UniFi ja App Store Connect

Suuna mõni neist teenustest webhooki URL-ile ja mssgs tunneb selle ära ning postitab korraliku kaardi, ilma et peaksid payloadi kirjutama. Vaata integratsioone. Need saavad vastuseks {"success": true} ja callback URL-i ei tule.