---
title: "Webhooki: objavljaj sporočila v kanalu mssgs"
description: "Pošlji sporočilo ali kartico v kanal mssgs iz CI, nadzornega sistema ali katere koli skripte z eno zahtevo HTTP. Formati, datoteke, podpisi, napake, omejitve."
canonical: https://docs.mss.gs/sl/webhooks
language: sl
---

# Objavljaj sporočila z webhookom

Webhook je URL, ki objavlja v tvoji skupnosti. Pošlji mu JSON iz česar koli, kar zna poslati zahtevo HTTP, na primer iz CI, nadzornega sistema, opravila cron ali skripte, in sporočilo se prikaže v kanalu.

## Kaj lahko narediš

- **Objavi besedilo ali kartico** Navadno besedilo ali kartica z naslovom, barvo, markdownom, polji in slikami.

- **Priloži datoteke** Do pet datotek na sporočilo: dnevniki, poročila, posnetki zaslona.

- **Dodaj gumbe** Povezave ali gumbi, ki spremenijo kartico ali pokličejo tvojo storitev.

- **Spremeni ga pozneje** Odgovor vsebuje callback URL, s katerim sporočilo posodobiš ali izbrišeš.

V aplikaciji

#### Build #1847 je uspel

Ena zahteva iz CI, ena kartica v #deploys. Ime na vrhu je ime, ki si ga dal webhooku.

- [Hiter začetek](#quick-start)

- [Kaj lahko pošlješ](#format)

- [Datoteke](#attachments)

- [Podpisovanje](#signing)

- [Odgovori in napake](#responses)

- [Omejitve](#limits)

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

## Hiter začetek

### Ustvari webhook

V namizni aplikaciji v svoji skupnosti odpri **Manage Server → Webhooks**, ustvari webhook, izberi kanale, v katerih sme objavljati, in kopiraj URL za kanal. Ima to obliko:

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

### Pošlji sporočilo

JSON podpiši s skrivnim ključem webhooka in ga pošlji z zahtevo POST. Webhook, ustvarjen v namizni aplikaciji, ga ima vedno: kopiraj ga iz polja **Webhook Secret** v nastavitvah webhooka.

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

### Preberi odgovor

Odgovor vsebuje ID sporočila in callback_url , s katerim sporočilo pozneje spremeniš.

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

## Kaj lahko pošlješ

Sporočilo je bodisi kratka oblika (besedilo z naslovom in barvo) bodisi cela kartica, obe pa lahko vsebujeta gumbe in datoteke. Ime na vrhu kartice je vedno ime samega webhooka. V nastavitvah webhooka določiš tudi, ali sme objavljati slike in omenjati ljudi.

### Kratka oblika

Dovolj za večino opozoril.

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

| Polje | Tip | Kaj naredi |
| --- | --- | --- |
| content | string | Besedilo sporočila. Obvezno, razen če pošlješ kartico ali datoteke. |
| color | string | blue (privzeto), green , orange , red , yellow ali purple . |
| title | string | Naslov nad besedilom. Privzeto je to ime webhooka. |

### Cela kartica

Pošlji message_container za kartico z naslovom kot povezavo, podnaslovom, markdownom, polji in slikami. Prek webhooka kartica sprejme type , color , title , title_url , sub_title , description , fields , avatar_url , image_url , image_base64 , images in polja za indikator nalaganja. Oznaka stanja, značka, statistika sprememb in skrito razmišljanje so namenjeni odgovorom na ukaze. Vsa polja so opisana na strani [kartice sporočil](https://docs.mss.gs/sl/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 je uspel

### Gumbi

Dodaj seznam actions in pod sporočilom se prikažejo gumbi. Kako delujejo, piše na strani [gumbi](https://docs.mss.gs/sl/buttons).

## Datoteke

S sporočilom objavi prave datoteke: dnevnik, poročilo, posnetek zaslona. Prikažejo se kot vsaka druga priponka, kot vrstica za prenos, slike, video in zvok pa neposredno v sporočilu. Tudi sporočilo samo z datotekami je v redu: izpusti content in kartico.

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

| Polje | Tip | Kaj naredi |
| --- | --- | --- |
| name | string | Ime, pod katerim se datoteka prenese. Obvezno. Pot se skrajša na zadnji del. |
| content_base64 | string | Bajti datoteke v base64, surovi ali kot URI data: . mssgs datoteko shrani, v sporočilu pa obdrži le povezavo. |
| mime_type | string | Vrsta vsebine v content_base64 . Privzeto text/plain . |
| url | string | Datoteka, ki že gostuje na mssgs: pot /static/... ali URL https://mss.gs/... . |

| Omejitev | Vrednost |
| --- | --- |
| Datoteke na sporočilo | **5** |
| Velikost datoteke po dekodiranju | **8 MB** |
| Ime datoteke | 200 znakov |
| Celotna zahteva | Približno 10 MB. Base64 datoteko poveča za tretjino, zato ena sama datoteka nad približno 7 MB ne bo šla skozi. |

### Zakaj url sprejema samo naslove mssgs

URL webhooka pogosto pristane prilepljen v druge nadzorne plošče. Če uide v javnost, ne sme nikomur omogočiti, da bi aplikacija vsakega člana prenesla datoteko s strežnika po njegovi izbiri. Če je tvoja datoteka drugje, jo pošlji kot content_base64 in mssgs jo bo gostil.

### Neuspešno nalaganje datoteke ne ustavi sporočila

Datoteke se preverijo vnaprej, naložijo pa pozneje. Če nalaganje spodleti, ta datoteka izpade, preostanek sporočila pa se vseeno objavi, brez napake: bolje izgubiti datoteko kot poročilo. Če je datoteka pomembna, preveri, ali je prispela.

### Datoteka iz ukazne vrstice

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

## Podpisovanje zahtev

Webhook s skrivnim ključem sprejme le zahteve, ki dokažejo, da ga poznajo, webhook, ustvarjen v namizni aplikaciji, pa ga ima vedno (**Webhook Secret** v njegovih nastavitvah). Surovo telo zahteve podpiši s HMAC-SHA256 in skrivnim ključem, šestnajstiški povzetek z malimi črkami pa pošlji v glavi X-Mssgs-Signature kot 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
});
```

Sprejeta je tudi GitHubova glava X-Hub-Signature-256 , zato webhook na GitHubu z istim skrivnim ključem deluje brez sprememb. Podpis nima časovnega žiga, zato ne prepreči ponovnega pošiljanja prestrežene zahteve: skrivnost, ki res šteje, ostaja URL.

## Odgovori in napake

Objavljeno sporočilo se vrne s svojim ID-jem in callback_url , s katerim ga lahko 30 minut posodabljaš ali ga izbrišeš.

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

Če ima sporočilo gumbe, odgovor vsebuje tudi stream_url : tok v živo z odgovori, reakcijami in pritiski gumbov na tem sporočilu, odprt 10 minut ali eno uro, če pošlješ "sse_event_extended_timeout": true . Glej [posodobitve v živo](https://docs.mss.gs/sl/live-updates).

### Statusne kode

| Status | Kdaj |
| --- | --- |
| 401 | Webhook ima skrivni ključ, podpis pa manjka ali je napačen. |
| 403 | Ta webhook ne sme objavljati v tem kanalu. |
| 404 | Na tem URL-ju ni webhooka. |
| 413 | Zahteva je prevelika. |
| 429 | Preveč zahtev. Upočasni in poskusi znova. |
| 502 | Sporočila ni bilo mogoče dostaviti. Poskusi znova. |

### Kode napak

| Koda | Pomen |
| --- | --- |
| MISSING_CONTENT | Ni ničesar za objavo: ni besedila, kartice niti datotek. |
| INVALID_MESSAGE_CONTAINER | message_container ni objekt. |
| INVALID_MESSAGE_CONTAINER_TYPE | Vrsta kartice ni ne embed_message ne system_message . |
| MISSING_MESSAGE_CONTAINER_DESCRIPTION | Kartica potrebuje opis, razen če gre za indikator nalaganja. |
| MISSING_MESSAGE_CONTAINER_LOADER_TEXT | Kartica z indikatorjem nalaganja potrebuje loader_text . |
| INVALID_WEBHOOK_BINDING | Ta webhook ne sme objavljati v tem kanalu. |
| INVALID_SIGNATURE | Glava s podpisom manjka ali je podpis napačen. |
| REQUEST_BODY_TOO_LARGE | Zahteva presega omejitev velikosti. |
| PUBLISH_FAILED | Sporočila ni bilo mogoče dostaviti. |
| INVALID_ACTIONS_FORMAT , INVALID_ACTION_MISSING_FIELDS , DUPLICATE_ACTION_ID , INVALID_TRIGGERS_FORMAT , INVALID_TRIGGER_MISSING_ACTION , INVALID_TRIGGER_ACTION_NOT_ALLOWED | Nekaj je narobe z gumbom. Glej [gumbe](https://docs.mss.gs/sl/buttons). |

### Napake pri datotekah

| Koda | Pomen |
| --- | --- |
| INVALID_ATTACHMENTS_FORMAT | attachments ni seznam ali pa kateri od vnosov ni objekt. |
| TOO_MANY_ATTACHMENTS | Več kot pet datotek. |
| MISSING_ATTACHMENT_NAME | Datoteka nima imena. |
| INVALID_ATTACHMENT_NAME | Od imena ne ostane nič uporabnega, na primer pri .. . |
| MISSING_ATTACHMENT_SOURCE | Ni ne url ne content_base64 . |
| AMBIGUOUS_ATTACHMENT_SOURCE | Hkrati url in content_base64 . |
| INVALID_ATTACHMENT_BASE64 | Base64 se ne da dekodirati. |
| ATTACHMENT_TOO_LARGE | Datoteka ima po dekodiranju več kot 8 MB. |
| INVALID_ATTACHMENT_URL | url ni naslov mssgs. |

## Omejitve

| Omejitev | Vrednost |
| --- | --- |
| Velikost zahteve | Približno 10 MB |
| Datoteke na sporočilo | 5, vsaka do 8 MB |
| Opis kartice | Do 50.000 bajtov. Po 1000 bajtih člani vidijo začetek in gumb **Show more**. |
| Posodabljanje sporočila po objavi | 30 minut, prek callback_url |
| Tok v živo za sporočilo z gumbi | 10 minut ali na zahtevo ena ura |

Število zahtev je omejeno. Ko dobiš 429 , počakaj, preden znova pošlješ, opozorila, ki prihajajo v valovih, pa združi v eno sporočilo.

## GitHub, UniFi in App Store Connect

Usmeri eno od teh storitev na URL webhooka in mssgs jo prepozna ter objavi pravo kartico, ne da bi ti moral pisati payload. Glej [integracije](https://mss.gs/sl/integrations). Te storitve dobijo odgovor {"success": true} brez callback URL-ja.

| Vir | Prepoznan po | Kaj objavi |
| --- | --- | --- |
| GitHub | Glava x-github-event | Pushi, pull requesti in pregledi, issueji in komentarji, veje in oznake, izdaje. Val sprememb v enem issueju ali pull requestu se zbere v eno kartico. |
| UniFi Protect | User agent protect-alarm-manager | Zvonjenje na vratih, gibanje ter ljudje, vozila ali paketi, ki jih zaznajo tvoje kamere. |
| App Store Connect | Telo njegovih obvestil ali glava x-apple-signature | Obvestila App Store Connect. |

## Gradi naprej