---
title: "Webhookit: lähetä viestejä mssgs-kanavalle"
description: "Lähetä viesti tai kortti mssgs-kanavalle CI:stä, valvonnasta tai skriptistä yhdellä HTTP-pyynnöllä. Muodot, tiedostot, allekirjoitus, virheet, rajat ja GitHub."
canonical: https://docs.mss.gs/fi/webhooks
language: fi
---

# Lähetä viestejä webhookilla

Webhook on URL, joka julkaisee viestejä yhteisöösi. Lähetä sille JSONia mistä tahansa, mikä osaa tehdä HTTP-pyynnön, kuten CI:stä, valvonnasta, cron-ajosta tai skriptistä, niin viesti ilmestyy kanavalle.

## Mitä voit tehdä

- **Julkaise tekstiä tai kortti** Pelkkää tekstiä tai kortti, jossa on otsikko, väri, markdownia, kenttiä ja kuvia.

- **Liitä tiedostoja** Enintään viisi tiedostoa viestiä kohden: lokeja, raportteja, kuvakaappauksia.

- **Lisää painikkeita** Linkkejä tai painikkeita, jotka muuttavat korttia tai tavoittavat palvelusi.

- **Muuta viestiä myöhemmin** Vastauksessa on callback-URL, jolla viestin voi päivittää tai poistaa.

Sovelluksessa

#### Build #1847 onnistui

Yksi pyyntö CI:stä, yksi kortti #deploys-kanavalla. Ylhäällä näkyvä nimi on se, jonka annoit webhookille.

- [Pika-aloitus](#quick-start)

- [Mitä voit lähettää](#format)

- [Tiedostot](#attachments)

- [Allekirjoitus](#signing)

- [Vastaukset ja virheet](#responses)

- [Rajat](#limits)

- [GitHub, UniFi, App Store](#special)

## Pika-aloitus

### 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:

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

### 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.

```bash
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"
```

### Lue vastaus

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

```json
{
  "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.

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

| Kenttä | Tyyppi | Mitä se tekee |
| --- | --- | --- |
| content | string | Viestin teksti. Pakollinen, ellet lähetä korttia tai tiedostoja. |
| color | string | blue (oletus), green , orange , red , yellow tai purple . |
| title | string | Otsikko tekstin yläpuolella. Oletuksena webhookin nimi. |

### 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](https://docs.mss.gs/fi/bots).

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

#### Build #1847 onnistui

### Painikkeet

Lisää actions -taulukko, niin viestin alle tulee painikkeita. Niiden toiminta on kuvattu sivulla [painikkeet](https://docs.mss.gs/fi/buttons).

## 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.

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

| Kenttä | Tyyppi | Mitä se tekee |
| --- | --- | --- |
| name | string | Tiedostonimi, jolla tiedosto ladataan. Pakollinen. Polusta jätetään vain viimeinen osa. |
| content_base64 | string | Tiedoston tavut base64-muodossa, raakana tai data: -URI:na. mssgs tallentaa tiedoston ja säilyttää viestissä vain linkin. |
| mime_type | string | Kentän content_base64 sisältötyyppi. Oletus on text/plain . |
| url | string | Tiedosto, joka on jo mssgs:n palvelimella: /static/... -polku tai https://mss.gs/... -URL. |

| Raja | Arvo |
| --- | --- |
| Tiedostoja viestiä kohden | **5** |
| Tiedoston koko dekoodauksen jälkeen | **8 MB** |
| Tiedostonimi | 200 merkkiä |
| Koko pyyntö | Noin 10 MB. Base64 kasvattaa tiedostoa kolmanneksella, joten yksittäinen yli noin 7 MB:n tiedosto ei mahdu mukaan. |

### 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ä

```bash
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> .

```javascript
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.

```json
{
  "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
HTTP/1.1 200 OK
Content-Type: application/json

{ "error": "ATTACHMENT_TOO_LARGE" }
```

```javascript
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](https://docs.mss.gs/fi/live-updates).

### Tilakoodit

| Tila | Milloin |
| --- | --- |
| 401 | Webhookilla on salaisuus, ja allekirjoitus puuttuu tai on väärä. |
| 403 | Tämä webhook ei saa julkaista kyseiselle kanavalle. |
| 404 | Tässä URL:ssa ei ole webhookia. |
| 413 | Pyyntö on liian suuri. |
| 429 | Liian monta pyyntöä. Hidasta ja yritä uudelleen. |
| 502 | Viestiä ei voitu toimittaa. Yritä uudelleen. |

### Virhekoodit

| Koodi | Merkitys |
| --- | --- |
| MISSING_CONTENT | Ei mitään julkaistavaa: ei tekstiä, korttia eikä tiedostoja. |
| INVALID_MESSAGE_CONTAINER | message_container ei ole olio. |
| INVALID_MESSAGE_CONTAINER_TYPE | Kortin tyyppi ei ole embed_message eikä system_message . |
| MISSING_MESSAGE_CONTAINER_DESCRIPTION | Kortti tarvitsee kuvauksen, ellei se ole latauskortti. |
| MISSING_MESSAGE_CONTAINER_LOADER_TEXT | Latauskortti tarvitsee kentän loader_text . |
| INVALID_WEBHOOK_BINDING | Tämä webhook ei saa julkaista kyseiselle kanavalle. |
| INVALID_SIGNATURE | Allekirjoitusheader puuttuu tai on väärä. |
| REQUEST_BODY_TOO_LARGE | Pyyntö ylittää kokorajan. |
| PUBLISH_FAILED | Viestiä ei voitu toimittaa. |
| INVALID_ACTIONS_FORMAT , INVALID_ACTION_MISSING_FIELDS , DUPLICATE_ACTION_ID , INVALID_TRIGGERS_FORMAT , INVALID_TRIGGER_MISSING_ACTION , INVALID_TRIGGER_ACTION_NOT_ALLOWED | Jossakin painikkeessa on vikaa. Katso [painikkeet](https://docs.mss.gs/fi/buttons). |

### Tiedostovirheet

| Koodi | Merkitys |
| --- | --- |
| INVALID_ATTACHMENTS_FORMAT | attachments ei ole lista, tai jokin sen alkio ei ole olio. |
| TOO_MANY_ATTACHMENTS | Yli viisi tiedostoa. |
| MISSING_ATTACHMENT_NAME | Tiedostolla ei ole nimeä. |
| INVALID_ATTACHMENT_NAME | Nimestä ei jää mitään käyttökelpoista, esimerkiksi .. . |
| MISSING_ATTACHMENT_SOURCE | Ei url - eikä content_base64 -kenttää. |
| AMBIGUOUS_ATTACHMENT_SOURCE | Sekä url että content_base64 . |
| INVALID_ATTACHMENT_BASE64 | Base64-data ei dekoodaudu. |
| ATTACHMENT_TOO_LARGE | Tiedosto on dekoodattuna yli 8 MB. |
| INVALID_ATTACHMENT_URL | url ei ole mssgs-osoite. |

## Rajat

| Raja | Arvo |
| --- | --- |
| Pyynnön koko | Noin 10 MB |
| Tiedostoja viestiä kohden | 5, kukin enintään 8 MB |
| Kortin kuvaus | Enintään 50 000 tavua. 1 000 tavun jälkeen jäsenet näkevät alun ja **Näytä lisää** -painikkeen. |
| Viestin päivittäminen jälkikäteen | 30 minuuttia, callback_url -osoitteen kautta |
| Painikkeellisen viestin reaaliaikainen virta | 10 minuuttia, tai pyynnöstä tunti |

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](https://mss.gs/fi/integrations). Nämä vastaavat {"success": true} ilman callback-URL:ia.

| Lähde | Tunnistetaan | Mitä se julkaisee |
| --- | --- | --- |
| GitHub | x-github-event -header | Pushit, pull requestit ja arvioinnit, issuet ja kommentit, haarat ja tagit sekä julkaisut. Useat peräkkäiset muutokset samaan issueen tai pull requestiin kootaan yhdeksi kortiksi. |
| UniFi Protect | protect-alarm-manager -user agent | Ovikellon soitot, liike sekä kameroidesi havaitsemat ihmiset, ajoneuvot ja paketit. |
| App Store Connect | Ilmoituksen body tai x-apple-signature -header | App Store Connect -ilmoitukset. |

## Jatka rakentamista