---
title: "Webhook’ai: skelbk žinutes mssgs kanale"
description: "Siųsk žinutę ar kortelę į mssgs kanalą iš CI, stebėsenos ar bet kurio skripto viena HTTP užklausa. Formatai, failai, parašai, klaidos ir limitai."
canonical: https://docs.mss.gs/lt/webhooks
language: lt
---

# Skelbk žinutes per webhook

Webhook yra URL, kuris skelbia į tavo bendruomenę. Siųsk jam JSON iš bet ko, kas gali atlikti HTTP užklausą, pavyzdžiui, iš CI, stebėsenos, cron užduoties ar skripto, ir žinutė atsiras kanale.

## Ką gali padaryti

- **Skelbk tekstą ar kortelę** Paprastas tekstas arba kortelė su pavadinimu, spalva, markdown, laukais ir paveikslėliais.

- **Pridėk failus** Iki penkių failų vienoje žinutėje: žurnalai, ataskaitos, ekrano nuotraukos.

- **Pridėk mygtukus** Nuorodos arba mygtukai, kurie keičia kortelę ar kreipiasi į tavo paslaugą.

- **Pakeisk vėliau** Atsakyme yra callback URL, skirtas žinutei atnaujinti ar ištrinti.

Programėlėje

#### Build #1847 sėkmingas

Viena užklausa iš CI, viena kortelė kanale #deploys. Viršuje rodomas pavadinimas, kurį davei webhook’ui.

- [Greita pradžia](#quick-start)

- [Ką gali siųsti](#format)

- [Failai](#attachments)

- [Pasirašymas](#signing)

- [Atsakymai ir klaidos](#responses)

- [Limitai](#limits)

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

## Greita pradžia

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

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

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

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

### Perskaityk atsakymą

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

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

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

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

| Laukas | Tipas | Ką daro |
| --- | --- | --- |
| content | string | Žinutės tekstas. Privalomas, nebent siunti kortelę ar failus. |
| color | string | blue (numatytoji), green , orange , red , yellow arba purple . |
| title | string | Pavadinimas virš teksto. Numatytai webhook’o pavadinimas. |

### 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](https://docs.mss.gs/lt/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 sėkmingas

### Mygtukai

Pridėk actions masyvą, kad po žinute atsirastų mygtukai. Kaip jie veikia, rasi puslapyje [mygtukai](https://docs.mss.gs/lt/buttons).

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

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

| Laukas | Tipas | Ką daro |
| --- | --- | --- |
| name | string | Failo pavadinimas atsisiunčiant. Privalomas. Kelias sutrumpinamas iki paskutinės dalies. |
| content_base64 | string | Failo baitai base64 formatu, gryni arba kaip data: URI. mssgs saugo failą, o žinutėje palieka tik nuorodą. |
| mime_type | string | content_base64 turinio tipas. Numatytai text/plain . |
| url | string | Failas, jau talpinamas mssgs: /static/... kelias arba https://mss.gs/... URL. |

| Limitas | Reikšmė |
| --- | --- |
| Failų vienoje žinutėje | **5** |
| Failo dydis po dekodavimo | **8 MB** |
| Failo pavadinimas | 200 simbolių |
| Visa užklausa | Apie 10 MB. Base64 padidina failą trečdaliu, todėl vienas didesnis nei maždaug 7 MB failas netilps. |

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

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

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

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

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.

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

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

### Būsenos kodai

| Būsena | Kada |
| --- | --- |
| 401 | Webhook turi slaptąjį raktą, o parašo nėra arba jis neteisingas. |
| 403 | Šis webhook negali skelbti tame kanale. |
| 404 | Šiuo URL webhook’o nėra. |
| 413 | Užklausa per didelė. |
| 429 | Per daug užklausų. Sulėtink ir bandyk dar kartą. |
| 502 | Žinutės nepavyko pristatyti. Bandyk dar kartą. |

### Klaidų kodai

| Kodas | Reikšmė |
| --- | --- |
| MISSING_CONTENT | Nėra ko skelbti: nėra nei teksto, nei kortelės, nei failų. |
| INVALID_MESSAGE_CONTAINER | message_container nėra objektas. |
| INVALID_MESSAGE_CONTAINER_TYPE | Kortelės tipas nėra nei embed_message , nei system_message . |
| MISSING_MESSAGE_CONTAINER_DESCRIPTION | Kortelei reikia aprašymo, nebent tai loader kortelė. |
| MISSING_MESSAGE_CONTAINER_LOADER_TEXT | Loader kortelei reikia loader_text . |
| INVALID_WEBHOOK_BINDING | Šis webhook negali skelbti tame kanale. |
| INVALID_SIGNATURE | Parašo antraštės nėra arba ji neteisinga. |
| REQUEST_BODY_TOO_LARGE | Užklausa viršija dydžio limitą. |
| PUBLISH_FAILED | Žinutės nepavyko pristatyti. |
| INVALID_ACTIONS_FORMAT , INVALID_ACTION_MISSING_FIELDS , DUPLICATE_ACTION_ID , INVALID_TRIGGERS_FORMAT , INVALID_TRIGGER_MISSING_ACTION , INVALID_TRIGGER_ACTION_NOT_ALLOWED | Kažkas negerai su mygtuku. Žr. [mygtukai](https://docs.mss.gs/lt/buttons). |

### Failų klaidos

| Kodas | Reikšmė |
| --- | --- |
| INVALID_ATTACHMENTS_FORMAT | attachments nėra sąrašas arba kuris nors įrašas nėra objektas. |
| TOO_MANY_ATTACHMENTS | Daugiau nei penki failai. |
| MISSING_ATTACHMENT_NAME | Failas neturi pavadinimo. |
| INVALID_ATTACHMENT_NAME | Iš pavadinimo nelieka nieko tinkamo, pavyzdžiui, .. . |
| MISSING_ATTACHMENT_SOURCE | Nėra nei url , nei content_base64 . |
| AMBIGUOUS_ATTACHMENT_SOURCE | Yra ir url , ir content_base64 . |
| INVALID_ATTACHMENT_BASE64 | Base64 nepavyksta dekoduoti. |
| ATTACHMENT_TOO_LARGE | Failas po dekodavimo didesnis nei 8 MB. |
| INVALID_ATTACHMENT_URL | url nėra mssgs adresas. |

## Limitai

| Limitas | Reikšmė |
| --- | --- |
| Užklausos dydis | Apie 10 MB |
| Failų vienoje žinutėje | 5, kiekvienas iki 8 MB |
| Kortelės aprašymas | Iki 50 000 baitų. Viršijus 1 000 baitų, nariai mato pradžią ir mygtuką **Show more**. |
| Žinutės atnaujinimas po paskelbimo | 30 minučių, per callback_url |
| Žinutės su mygtukais gyvas srautas | 10 minučių arba valanda, jei paprašai |

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](https://mss.gs/lt/integrations). Šios paslaugos atsakymu gauna {"success": true} ir jokio callback URL.

| Šaltinis | Atpažįstama pagal | Ką skelbia |
| --- | --- | --- |
| GitHub | Antraštė x-github-event | Push’ai, pull request’ai ir peržiūros, issues ir komentarai, šakos ir žymos, leidimai. Daug pakeitimų per trumpą laiką viename issue ar pull request’e sujungiami į vieną kortelę. |
| UniFi Protect | User agent protect-alarm-manager | Durų skambučiai, judesys ir tavo kamerų aptikti žmonės, transporto priemonės ar siuntiniai. |
| App Store Connect | Jo pranešimų turinys arba antraštė x-apple-signature | App Store Connect pranešimai. |

## Kurk toliau