---
title: "Webhooky: posílej zprávy do kanálu mssgs"
description: "Pošli zprávu nebo kartu do kanálu mssgs z CI, monitoringu nebo skriptu jedním HTTP požadavkem. Formáty, soubory, podepisování, chyby a limity."
canonical: https://docs.mss.gs/cs/webhooks
language: cs
---

# Posílej zprávy webhookem

Webhook je URL adresa, přes kterou posíláš zprávy do své komunity. Pošli na ni JSON z čehokoli, co umí odeslat HTTP požadavek, třeba z CI, monitoringu, cron úlohy nebo skriptu, a zpráva se objeví v kanálu.

## Co s tím můžeš dělat

- **Pošli text nebo kartu** Prostý text, nebo karta s nadpisem, barvou, markdownem, poli a obrázky.

- **Přilož soubory** Až pět souborů na zprávu: logy, reporty, snímky obrazovky.

- **Přidej tlačítka** Odkazy nebo tlačítka, která změní kartu nebo zavolají tvou službu.

- **Uprav ji později** Odpověď obsahuje callback URL, přes kterou zprávu aktualizuješ nebo smažeš.

V aplikaci

#### Build #1847 prošel

Jeden požadavek z CI, jedna karta v #deploys. Nahoře je jméno, které má tvůj webhook v nastavení.

- [Rychlý start](#quick-start)

- [Co můžeš poslat](#format)

- [Soubory](#attachments)

- [Podepisování](#signing)

- [Odpovědi a chyby](#responses)

- [Limity](#limits)

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

## Rychlý start

### Vytvoř webhook

V desktopové aplikaci otevři ve své komunitě **Manage Server → Webhooks**, vytvoř webhook, vyber kanály, do kterých smí posílat, a zkopíruj URL pro daný kanál. Vypadá takto:

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

### Pošli zprávu

Podepiš JSON tajným klíčem webhooku a pošli ho metodou POST. Webhook vytvořený v desktopové aplikaci ho má vždy: zkopíruj ho z pole **Webhook Secret** v nastavení webhooku.

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

### Přečti odpověď

Odpověď ti vrátí id zprávy a callback_url pro pozdější úpravu zprávy.

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

## Co můžeš poslat

Zpráva je buď krátká forma (text s nadpisem a barvou), nebo plná karta, a obě můžou nést tlačítka a soubory. Jméno nahoře na kartě je vždy jméno samotného webhooku. V nastavení webhooku také určíš, jestli smí posílat obrázky a zmiňovat lidi.

### Krátká forma

Na většinu upozornění stačí.

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

| Pole | Typ | Co dělá |
| --- | --- | --- |
| content | string | Text zprávy. Povinný, pokud neposíláš kartu nebo soubory. |
| color | string | blue (výchozí), green , orange , red , yellow nebo purple . |
| title | string | Nadpis nad textem. Výchozí je jméno webhooku. |

### Plná karta

Pošli message_container a dostaneš kartu s nadpisem jako odkazem, podnadpisem, markdownem, poli a obrázky. Přes webhook karta přijímá type , color , title , title_url , sub_title , description , fields , avatar_url , image_url , image_base64 , images a pole loaderu. Štítek stavu, odznak, statistiky diffu a sbalené uvažování patří odpovědím na příkazy. Všechna pole najdeš na stránce [karty zpráv](https://docs.mss.gs/cs/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 prošel

### Tlačítka

Přidej pole actions a pod zprávou se objeví tlačítka. Jak fungují, popisuje stránka [tlačítka](https://docs.mss.gs/cs/buttons).

## Soubory

Posílej se zprávou skutečné soubory: log, report, snímek obrazovky. Zobrazí se jako každá jiná příloha, jako řádek ke stažení, a obrázky, video a zvuk přímo ve zprávě. Zpráva jen se soubory je v pořádku: vynech content i kartu.

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

| Pole | Typ | Co dělá |
| --- | --- | --- |
| name | string | Název, pod kterým se soubor stáhne. Povinný. Cesta se zkrátí na svou poslední část. |
| content_base64 | string | Bajty souboru v base64, holé nebo jako URI data: . mssgs soubor uloží a ve zprávě nechá jen odkaz. |
| mime_type | string | Typ obsahu content_base64 . Výchozí je text/plain . |
| url | string | Soubor, který už mssgs hostuje: cesta /static/... nebo URL https://mss.gs/... . |

| Limit | Hodnota |
| --- | --- |
| Souborů na zprávu | **5** |
| Velikost souboru po dekódování | **8 MB** |
| Název souboru | 200 znaků |
| Celý požadavek | Zhruba 10 MB. Base64 soubor zvětší o třetinu, takže jeden soubor větší než zhruba 7 MB se nevejde. |

### Proč url bere jen adresy mssgs

URL webhooku často skončí vložená v dalších dashboardech. Když unikne, nesmí nikomu umožnit, aby aplikace každého člena stahovala soubor ze serveru, který si sám vybral. Pokud je tvůj soubor jinde, pošli ho jako content_base64 a mssgs ho bude hostovat.

### Nepovedené nahrání souboru zprávu nezastaví

Soubory se kontrolují předem, ale nahrávají se až potom. Když nahrání selže, ten soubor vypadne a zbytek zprávy se přesto zveřejní, bez chyby: přijít o soubor je lepší než přijít o report. Pokud na souboru záleží, ověř si, že dorazil.

### Soubor z příkazové řádky

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

## Podepisování požadavků

Webhook s tajným klíčem přijímá jen požadavky, které dokážou, že ho znají, a webhook vytvořený v desktopové aplikaci ho má vždy (**Webhook Secret** v jeho nastavení). Podepiš surové tělo požadavku pomocí HMAC-SHA256 s tajným klíčem a pošli hex digest malými písmeny v hlavičce X-Mssgs-Signature jako 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
});
```

Přijímá se i vlastní hlavička GitHubu X-Hub-Signature-256 , takže webhook z GitHubu se stejným tajným klíčem funguje beze změn. Podpis nemá časové razítko, takže nezabrání opakovanému odeslání zachyceného požadavku: tajemstvím, na kterém opravdu záleží, zůstává URL.

## Odpovědi a chyby

Zveřejněná zpráva se vrátí se svým id a odkazem callback_url , přes který ji můžeš 30 minut aktualizovat nebo smazat.

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

Když má zpráva tlačítka, odpověď obsahuje i stream_url : živý stream odpovědí, reakcí a stisknutí tlačítek u té zprávy, otevřený 10 minut, nebo hodinu, když pošleš "sse_event_extended_timeout": true . Viz [živé aktualizace](https://docs.mss.gs/cs/live-updates).

### Stavové kódy

| Status | Kdy |
| --- | --- |
| 401 | Webhook má tajný klíč a podpis chybí nebo je špatný. |
| 403 | Tento webhook nesmí posílat do tohoto kanálu. |
| 404 | Na této URL žádný webhook není. |
| 413 | Požadavek je příliš velký. |
| 429 | Příliš mnoho požadavků. Zpomal a zkus to znovu. |
| 502 | Zprávu se nepodařilo doručit. Zkus to znovu. |

### Chybové kódy

| Kód | Význam |
| --- | --- |
| MISSING_CONTENT | Není co zveřejnit: žádný text, žádná karta ani soubory. |
| INVALID_MESSAGE_CONTAINER | message_container není objekt. |
| INVALID_MESSAGE_CONTAINER_TYPE | Typ karty není embed_message ani system_message . |
| MISSING_MESSAGE_CONTAINER_DESCRIPTION | Karta potřebuje popis, pokud to není loader. |
| MISSING_MESSAGE_CONTAINER_LOADER_TEXT | Karta loaderu potřebuje loader_text . |
| INVALID_WEBHOOK_BINDING | Tento webhook nesmí posílat do tohoto kanálu. |
| INVALID_SIGNATURE | Hlavička s podpisem chybí nebo je podpis špatný. |
| REQUEST_BODY_TOO_LARGE | Požadavek překračuje limit velikosti. |
| PUBLISH_FAILED | Zprávu se nepodařilo doručit. |
| INVALID_ACTIONS_FORMAT , INVALID_ACTION_MISSING_FIELDS , DUPLICATE_ACTION_ID , INVALID_TRIGGERS_FORMAT , INVALID_TRIGGER_MISSING_ACTION , INVALID_TRIGGER_ACTION_NOT_ALLOWED | Něco je špatně s tlačítkem. Viz [tlačítka](https://docs.mss.gs/cs/buttons). |

### Chyby souborů

| Kód | Význam |
| --- | --- |
| INVALID_ATTACHMENTS_FORMAT | attachments není seznam, nebo některá položka není objekt. |
| TOO_MANY_ATTACHMENTS | Víc než pět souborů. |
| MISSING_ATTACHMENT_NAME | Soubor nemá název. |
| INVALID_ATTACHMENT_NAME | Z názvu nezbude nic použitelného, třeba u .. . |
| MISSING_ATTACHMENT_SOURCE | Chybí url i content_base64 . |
| AMBIGUOUS_ATTACHMENT_SOURCE | Zároveň url i content_base64 . |
| INVALID_ATTACHMENT_BASE64 | Base64 nejde dekódovat. |
| ATTACHMENT_TOO_LARGE | Soubor má po dekódování víc než 8 MB. |
| INVALID_ATTACHMENT_URL | url není adresa mssgs. |

## Limity

| Limit | Hodnota |
| --- | --- |
| Velikost požadavku | Zhruba 10 MB |
| Souborů na zprávu | 5, každý až 8 MB |
| Popis karty | Až 50 000 bajtů. Po 1 000 bajtech členové uvidí začátek a tlačítko **Show more**. |
| Úprava zprávy po zveřejnění | 30 minut, přes callback_url |
| Živý stream zprávy s tlačítky | 10 minut, nebo hodinu na požádání |

Počet požadavků je omezený. Když dostaneš 429 , chvíli počkej, než pošleš další, a upozornění, která chodí v dávkách, spoj do jedné zprávy.

## GitHub, UniFi a App Store Connect

Nasměruj některou z těchto služeb na URL webhooku a mssgs ji pozná a zveřejní pořádnou kartu, bez psaní payloadu. Viz [integrace](https://mss.gs/cs/integrations). Tyto služby dostanou odpověď {"success": true} a žádnou callback URL.

| Zdroj | Pozná se podle | Co zveřejní |
| --- | --- | --- |
| GitHub | Hlavička x-github-event | Pushe, pull requesty a recenze, issues a komentáře, větve a tagy, vydání. Série změn v jednom issue nebo pull requestu se spojí do jedné karty. |
| UniFi Protect | User agent protect-alarm-manager | Zazvonění zvonku, pohyb a lidé, vozidla nebo balíky, které zachytí tvoje kamery. |
| App Store Connect | Tělo jeho notifikace nebo hlavička x-apple-signature | Notifikace z App Store Connect. |

## Tvoř dál