Lähetä viestejä webhookilla

Pika-aloitus

1. 1

   Luo webhook

   Avaa työpöytäsovelluksessa yhteisösi Hallitse palvelinta → Webhookit, luo webhook, valitse kanavat, joille se saa julkaista, ja kopioi kanavan URL. Se on tämän muotoinen:

   urlKopioi

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

2. 2

   Lähetä viesti

   Allekirjoita JSON webhookin salaisuudella ja lähetä se POST-pyynnöllä. Työpöytäsovelluksessa luodulla webhookilla on aina salaisuus: kopioi se kohdasta Webhookin salaisuus webhookin asetuksista.

   bashKopioi

   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

   Lue vastaus

   Vastauksesta saat viestin id:n sekä callback_url-osoitteen, jolla voit muuttaa viestiä myöhemmin.

   jsonKopioi

   {
     "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ä voit lähettää

Viesti on joko lyhyt muoto (teksti, otsikko ja väri) tai kokonainen kortti, ja kumpaankin voi liittää painikkeita ja tiedostoja. Kortin yläreunan nimi on aina webhookin oma nimi. Webhookin asetuksissa päätät myös, saako se julkaista kuvia ja mainita ihmisiä.

Lyhyt muoto

Riittää useimpiin hälytyksiin.

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

Kokonainen kortti

Lähetä message_container, niin saat kortin, jossa on linkitetty otsikko, alaotsikko, markdownia, kenttiä ja kuvia. Webhookin kautta kortti ottaa vastaan kentät type, color, title, title_url, sub_title, description, fields, avatar_url, image_url, image_base64, images sekä latausilmaisimen kentät. Tilapilleri, merkki, diff-luvut ja kokoontaitettu päättely ovat komentovastauksia varten. Jokainen kenttä on kuvattu sivulla viestikortit.

jsonKopioi

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

Viesti lähettäjältä CI

Build #1847 onnistui

Kaikki 212 testiä vihreänä haarassa main.

Duration

2m 34s

Commit

1a2b3c4

09:12

Painikkeet

Lisää actions-taulukko, niin viestin alle tulee painikkeita. Niiden toiminta on kuvattu sivulla painikkeet.

Tiedostot

Julkaise viestin mukana oikeita tiedostoja: loki, raportti, kuvakaappaus. Ne näkyvät kuten mikä tahansa muu liite, latausrivinä tai kuvien, videoiden ja äänen kohdalla suoraan viestissä. Pelkät tiedostot sisältävä viesti on kelvollinen: jätä content ja kortti pois.

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

Miksi url hyväksyy vain mssgs-osoitteita

Webhookin URL päätyy usein liitetyksi muihin hallintapaneeleihin. Vuotaneella URL:lla ei saa voida pakottaa jokaisen jäsenen sovellusta hakemaan tiedostoa vuotajan valitsemalta palvelimelta. Jos tiedostosi on muualla, lähetä se content_base64-kentässä, niin mssgs isännöi sen.

Epäonnistunut lataus ei kaada viestiä

Tiedostot tarkistetaan etukäteen, mutta ne ladataan vasta jälkikäteen. Jos lataus epäonnistuu, kyseinen tiedosto jätetään pois ja muu viesti julkaistaan silti ilman virhettä: tiedoston menettäminen on parempi kuin raportin menettäminen. Jos tiedosto on tärkeä, tarkista, että se tuli perille.

Tiedosto komentoriviltä

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

Pyyntöjen allekirjoittaminen

Webhook, jolla on salaisuus, hyväksyy vain pyynnöt, jotka todistavat tuntevansa sen, ja työpöytäsovelluksessa luodulla webhookilla on aina salaisuus (Webhookin salaisuus sen asetuksissa). Allekirjoita pyynnön raaka body HMAC-SHA256:lla salaisuutta käyttäen ja lähetä pienaakkosinen heksadesimaalitiiviste X-Mssgs-Signature-headerissa muodossa 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
});

Myös GitHubin oma X-Hub-Signature-256-header hyväksytään, joten GitHub-webhook samalla salaisuudella toimii sellaisenaan. Allekirjoituksessa ei ole aikaleimaa, joten se ei estä kaapatun pyynnön lähettämistä uudelleen: URL on edelleen se salaisuus, jolla on merkitystä.

Vastaukset ja virheet

Julkaistu viesti palauttaa id:nsä ja callback_url-osoitteen, jolla sen voi päivittää tai poistaa 30 minuutin ajan.

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

Kun viestissä on painikkeita, vastauksessa on myös stream_url: reaaliaikainen virta viestin vastauksista, reaktioista ja painikkeiden painalluksista. Se on auki 10 minuuttia, tai tunnin, kun lähetät "sse_event_extended_timeout": true. Katso live-päivitykset.

Tilakoodit

Virhekoodit

Tiedostovirheet

Rajat

Pyyntöjen määrää rajoitetaan. Kun saat vastauksen 429, odota ennen kuin lähetät uudelleen, ja kokoa ryöppyinä saapuvat hälytykset yhteen viestiin.

GitHub, UniFi ja App Store Connect

Osoita jokin näistä palveluista webhookin URL:iin, niin mssgs tunnistaa sen ja julkaisee siistin kortin ilman, että sinun tarvitsee kirjoittaa payloadia. Katso integraatiot. Nämä vastaavat {"success": true} ilman callback-URL:ia.