---
title: "Webhookok: üzenetküldés egy mssgs-csatornába"
description: "Küldj üzenetet vagy kártyát egy mssgs-csatornába CI-ból, monitorozásból vagy szkriptből egyetlen HTTP-kéréssel. Formátumok, fájlok, aláírás, hibák."
canonical: https://docs.mss.gs/hu/webhooks
language: hu
---

# Üzenetküldés webhookkal

A webhook egy URL, amelyen keresztül üzenetek kerülnek a közösségedbe. Küldj neki JSON-t bármiből, ami HTTP-kérést tud indítani, például CI-ból, monitorozásból, cron jobból vagy szkriptből, és az üzenet megjelenik a csatornában.

## Mire használhatod

- **Küldj szöveget vagy kártyát** Sima szöveget, vagy kártyát címmel, színnel, markdownnal, mezőkkel és képekkel.

- **Csatolj fájlokat** Üzenetenként legfeljebb öt fájlt: naplókat, jelentéseket, képernyőképeket.

- **Adj hozzá gombokat** Linkeket, vagy gombokat, amelyek módosítják a kártyát, vagy elérik a szolgáltatásodat.

- **Módosítsd később** A válaszban kapsz egy callback URL-t, amellyel frissítheted vagy törölheted az üzenetet.

Az alkalmazásban

#### Build #1847: sikeres

Egy kérés a CI-ból, egy kártya a #deploys csatornában. A felül látható név az, amelyet a webhooknak adtál.

- [Gyors kezdés](#quick-start)

- [Mit küldhetsz](#format)

- [Fájlok](#attachments)

- [Aláírás](#signing)

- [Válaszok és hibák](#responses)

- [Korlátok](#limits)

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

## Gyors kezdés

### Hozd létre a webhookot

Az asztali alkalmazásban nyisd meg a közösséged **Manage Server → Webhooks** menüpontját, hozz létre egy webhookot, válaszd ki, mely csatornákba küldhet üzenetet, és másold ki egy csatorna URL-jét. Így néz ki:

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

### Küldj egy üzenetet

Írd alá a JSON-t a webhook titkos kulcsával, és küldd el POST-kéréssel. Az asztali alkalmazásban létrehozott webhooknak mindig van ilyen kulcsa: másold ki a webhook beállításainak **Webhook Secret** mezőjéből.

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

### Olvasd el a választ

A válaszban megkapod az üzenet azonosítóját, és egy callback_url címet, amellyel később módosíthatod az üzenetet.

```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 küldhetsz

Egy üzenet vagy rövid formájú (szöveg címmel és színnel), vagy teljes kártya, és mindkettő tartalmazhat gombokat és fájlokat. A kártya tetején mindig a webhook saját neve áll. A webhook beállításaiban azt is eldöntöd, hogy küldhet-e képeket, és megemlíthet-e másokat.

### Rövid forma

A legtöbb riasztáshoz elég.

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

| Mező | Típus | Mit csinál |
| --- | --- | --- |
| content | string | Az üzenet szövege. Kötelező, hacsak nem kártyát vagy fájlokat küldesz. |
| color | string | blue (alapértelmezett), green , orange , red , yellow vagy purple . |
| title | string | Cím a szöveg fölött. Alapértelmezés szerint a webhook neve. |

### Teljes kártya

Küldj egy message_container objektumot, ha linkelt címmel, alcímmel, markdownnal, mezőkkel és képekkel ellátott kártyát szeretnél. Webhookon keresztül a kártya ezeket a mezőket fogadja: type , color , title , title_url , sub_title , description , fields , avatar_url , image_url , image_base64 , images , valamint a betöltésjelző mezői. A státuszcímke, a jelvény, a diff-statisztika és az összecsukott gondolatmenet a parancsokra adott válaszokhoz való. Minden mező leírása az [üzenetkártyák](https://docs.mss.gs/hu/bots) oldalon található.

```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: sikeres

### Gombok

Egy actions tömbbel gombokat tehetsz az üzenet alá. A működésüket a [gombok](https://docs.mss.gs/hu/buttons) oldal írja le.

## Fájlok

Küldj valódi fájlokat az üzenettel: naplót, jelentést, képernyőképet. Ugyanúgy jelennek meg, mint bármely más melléklet: letöltési sorként, a képek, videók és hangfájlok pedig közvetlenül az üzenetben. Csak fájlokat tartalmazó üzenet is küldhető: hagyd el a content mezőt és a kártyát.

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

| Mező | Típus | Mit csinál |
| --- | --- | --- |
| name | string | A fájlnév, amelyen letöltődik. Kötelező. Egy elérési útból csak az utolsó rész marad meg. |
| content_base64 | string | A fájl bájtjai base64-ben, nyersen vagy data: URI-ként. Az mssgs tárolja a fájlt, az üzenetben csak egy link marad. |
| mime_type | string | A content_base64 tartalomtípusa. Alapértelmezés: text/plain . |
| url | string | Az mssgs-en már tárolt fájl: egy /static/... elérési út vagy egy https://mss.gs/... URL. |

| Korlát | Érték |
| --- | --- |
| Fájlok üzenetenként | **5** |
| Fájlméret dekódolás után | **8 MB** |
| Fájlnév | 200 karakter |
| A teljes kérés | Körülbelül 10 MB. A base64 egyharmaddal megnöveli a fájlt, így egy nagyjából 7 MB-nál nagyobb fájl már nem fér bele. |

### Miért fogad el az url csak mssgs-címeket

A webhook URL-je gyakran más irányítópultokra is bekerül. Ha kiszivárog, akkor sem szabad, hogy bárki rávehesse vele minden tag alkalmazását arra, hogy egy általa választott szerverről töltsön le fájlt. Ha a fájlod máshol van, küldd el a content_base64 mezőben, és az mssgs tárolja.

### A sikertelen feltöltés nem buktatja el az üzenetet

A fájlokat a rendszer előre ellenőrzi, de csak utána tölti fel. Ha egy feltöltés nem sikerül, az a fájl kimarad, az üzenet többi része pedig hiba nélkül megjelenik: jobb elveszíteni a fájlt, mint a jelentést. Ha egy fájl fontos, ellenőrizd, hogy megérkezett-e.

### Fájl küldése parancssorból

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

## Kérések aláírása

A titkos kulccsal rendelkező webhook csak olyan kéréseket fogad el, amelyek igazolják, hogy ismerik a kulcsot, és az asztali alkalmazásban létrehozott webhooknak mindig van ilyen (**Webhook Secret** a beállításaiban). Írd alá a nyers kéréstörzset HMAC-SHA256-tal a titkos kulcs használatával, és küldd el a kisbetűs hex digestet az X-Mssgs-Signature fejlécben, sha256=<hex> formában.

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

A GitHub saját X-Hub-Signature-256 fejlécét is elfogadjuk, így egy ugyanazzal a titkos kulccsal beállított GitHub-webhook változtatás nélkül működik. Az aláírás nem tartalmaz időbélyeget, ezért nem akadályozza meg, hogy egy elfogott kérést újra elküldjenek: a valódi titok továbbra is az URL.

## Válaszok és hibák

A sikeresen elküldött üzenet visszaadja az azonosítóját és egy callback_url címet, amellyel 30 percig frissítheted vagy törölheted.

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

Ha az üzenetnek vannak gombjai, a válaszban egy stream_url is szerepel: az üzenetre érkező válaszok, reakciók és gombnyomások élő streamje, amely 10 percig marad nyitva, vagy egy óráig, ha "sse_event_extended_timeout": true értéket küldesz. Lásd: [élő frissítések](https://docs.mss.gs/hu/live-updates).

### Státuszkódok

| Státusz | Mikor |
| --- | --- |
| 401 | A webhooknak van titkos kulcsa, és az aláírás hiányzik vagy hibás. |
| 403 | Ez a webhook nem küldhet üzenetet abba a csatornába. |
| 404 | Ezen az URL-en nincs webhook. |
| 413 | A kérés túl nagy. |
| 429 | Túl sok kérés. Lassíts, és próbáld újra. |
| 502 | Az üzenetet nem sikerült kézbesíteni. Próbáld újra. |

### Hibakódok

| Kód | Jelentés |
| --- | --- |
| MISSING_CONTENT | Nincs mit elküldeni: se szöveg, se kártya, se fájl. |
| INVALID_MESSAGE_CONTAINER | A message_container nem objektum. |
| INVALID_MESSAGE_CONTAINER_TYPE | A kártya típusa nem embed_message és nem is system_message . |
| MISSING_MESSAGE_CONTAINER_DESCRIPTION | A kártyához leírás kell, hacsak nem betöltésjelző. |
| MISSING_MESSAGE_CONTAINER_LOADER_TEXT | A betöltésjelző kártyához loader_text kell. |
| INVALID_WEBHOOK_BINDING | Ez a webhook nem küldhet üzenetet abba a csatornába. |
| INVALID_SIGNATURE | Az aláírás fejléce hiányzik vagy hibás. |
| REQUEST_BODY_TOO_LARGE | A kérés túllépi a méretkorlátot. |
| PUBLISH_FAILED | Az üzenetet nem sikerült kézbesíteni. |
| INVALID_ACTIONS_FORMAT , INVALID_ACTION_MISSING_FIELDS , DUPLICATE_ACTION_ID , INVALID_TRIGGERS_FORMAT , INVALID_TRIGGER_MISSING_ACTION , INVALID_TRIGGER_ACTION_NOT_ALLOWED | Valami nem stimmel egy gombbal. Lásd: [gombok](https://docs.mss.gs/hu/buttons). |

### Fájlhibák

| Kód | Jelentés |
| --- | --- |
| INVALID_ATTACHMENTS_FORMAT | Az attachments nem lista, vagy valamelyik eleme nem objektum. |
| TOO_MANY_ATTACHMENTS | Ötnél több fájl. |
| MISSING_ATTACHMENT_NAME | Egy fájlnak nincs neve. |
| INVALID_ATTACHMENT_NAME | A névből semmi használható nem marad, például .. esetén. |
| MISSING_ATTACHMENT_SOURCE | Se url , se content_base64 nincs megadva. |
| AMBIGUOUS_ATTACHMENT_SOURCE | url és content_base64 is meg van adva. |
| INVALID_ATTACHMENT_BASE64 | A base64 nem dekódolható. |
| ATTACHMENT_TOO_LARGE | Egy fájl dekódolás után nagyobb 8 MB-nál. |
| INVALID_ATTACHMENT_URL | Az url nem mssgs-cím. |

## Korlátok

| Korlát | Érték |
| --- | --- |
| Kérés mérete | Körülbelül 10 MB |
| Fájlok üzenetenként | 5, egyenként legfeljebb 8 MB |
| Kártya leírása | Legfeljebb 50 000 bájt. 1000 bájt felett a tagok az elejét látják, alatta egy **Show more** gombbal. |
| Az üzenet utólagos frissítése | 30 perc, a callback_url címen keresztül |
| Gombos üzenet élő streamje | 10 perc, vagy kérésre egy óra |

A kérések gyakorisága korlátozott. Ha 429 választ kapsz, várj, mielőtt újra küldenél, és a hullámokban érkező riasztásokat fogd össze egyetlen üzenetbe.

## GitHub, UniFi és App Store Connect

Irányítsd valamelyik szolgáltatást egy webhook URL-re, és az mssgs felismeri, majd rendes kártyát küld be, payload írása nélkül. Lásd: [integrációk](https://mss.gs/hu/integrations). Ezek {"success": true} választ kapnak, callback URL nélkül.

| Forrás | Mi alapján ismeri fel | Mit küld be |
| --- | --- | --- |
| GitHub | Az x-github-event fejléc | Pushok, pull requestek és review-k, issue-k és hozzászólások, branchek és tagek, release-ek. Ha egy issue-n vagy pull requesten rövid idő alatt sok változás történik, azok egyetlen kártyába kerülnek. |
| UniFi Protect | A protect-alarm-manager user agent | Csengetések, mozgás, valamint a kameráid által észlelt emberek, járművek vagy csomagok. |
| App Store Connect | Az értesítés törzse vagy az x-apple-signature fejléc | App Store Connect-értesítések. |

## Építs tovább