---
title: "Уебхукове: публикувайте съобщения в канал на mssgs"
description: "Изпратете съобщение или карта в канал на mssgs от CI, мониторинг или скрипт с една HTTP заявка. Формати, файлове, подписване, грешки и лимити."
canonical: https://docs.mss.gs/bg/webhooks
language: bg
---

# Публикувайте съобщения с уебхук

Уебхукът е URL адрес, който публикува във вашата общност. Изпратете му JSON от всичко, което може да направи HTTP заявка, например CI, мониторинг, cron задача или скрипт, и съобщението се появява в канала.

## Какво можете да направите

- **Публикувайте текст или карта** Обикновен текст или карта със заглавие, цвят, markdown, полета и изображения.

- **Прикачвайте файлове** До пет файла на съобщение: логове, отчети, екранни снимки.

- **Добавяйте бутони** Линкове или бутони, които променят картата или стигат до вашата услуга.

- **Променяйте го по-късно** Отговорът съдържа callback URL, с който да обновите или изтриете съобщението.

В приложението

#### Build #1847 е успешен

Една заявка от CI, една карта в #deploys. Името отгоре е името, което сте дали на уебхука.

- [Бърз старт](#quick-start)

- [Какво можете да изпратите](#format)

- [Файлове](#attachments)

- [Подписване](#signing)

- [Отговори и грешки](#responses)

- [Лимити](#limits)

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

## Бърз старт

### Създайте уебхука

В настолното приложение отворете **Manage Server → Webhooks** на вашата общност, създайте уебхук, изберете каналите, в които може да публикува, и копирайте URL адреса за даден канал. Той изглежда така:

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

### Изпратете съобщение

Подпишете JSON с тайния ключ на уебхука и го изпратете с POST. Уебхук, създаден в настолното приложение, винаги има такъв: копирайте го от **Webhook Secret** в настройките на уебхука.

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

### Прочетете отговора

Отговорът ви дава id на съобщението и callback_url , с който да промените съобщението по-късно.

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

## Какво можете да изпратите

Съобщението е или в кратка форма (текст със заглавие и цвят), или пълна карта, и двете могат да носят бутони и файлове. Името отгоре на картата винаги е собственото име на уебхука. В настройките на уебхука решавате също дали може да публикува изображения и да споменава хора.

### Кратка форма

Достатъчна е за повечето известия.

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

| Поле | Тип | Какво прави |
| --- | --- | --- |
| content | string | Текстът на съобщението. Задължителен, освен ако не изпращате карта или файлове. |
| color | string | blue (по подразбиране), green , orange , red , yellow или purple . |
| title | string | Заглавие над текста. По подразбиране е името на уебхука. |

### Пълна карта

Изпратете message_container за карта със заглавие с линк, подзаглавие, markdown, полета и изображения. Чрез уебхук картата приема type , color , title , title_url , sub_title , description , fields , avatar_url , image_url , image_base64 , images и полетата за индикатор за зареждане. Етикетът за статус, значката, статистиката на diff и сгънатите разсъждения са за отговори на команди. Всички полета са описани в [карти на съобщения](https://docs.mss.gs/bg/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 е успешен

### Бутони

Добавете масив actions , за да поставите бутони под съобщението. Как работят, е описано в [бутони](https://docs.mss.gs/bg/buttons).

## Файлове

Публикувайте истински файлове със съобщението: лог, отчет, екранна снимка. Те се показват като всеки друг прикачен файл: като ред за изтегляне, а изображенията, видеото и аудиото направо в съобщението. Съобщение само с файлове също е наред: пропуснете content и картата.

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

| Поле | Тип | Какво прави |
| --- | --- | --- |
| name | string | Името, с което се изтегля файлът. Задължително. Пътят се съкращава до последната си част. |
| content_base64 | string | Байтовете на файла в base64, сурови или като data: URI. mssgs съхранява файла и пази в съобщението само линк. |
| mime_type | string | Типът на съдържанието на content_base64 . По подразбиране text/plain . |
| url | string | Файл, който вече се хоства в mssgs: път /static/... или URL https://mss.gs/... . |

| Лимит | Стойност |
| --- | --- |
| Файлове на съобщение | **5** |
| Размер на файл след декодиране | **8 MB** |
| Име на файл | 200 знака |
| Цялата заявка | Около 10 MB. Base64 прави файла с една трета по-голям, така че отделен файл над приблизително 7 MB няма да се побере. |

### Защо url приема само адреси на mssgs

URL адресът на уебхук често се озовава в табла на други услуги. Ако изтече, той не бива да позволява на някого да накара приложението на всеки член да изтегли файл от сървър по негов избор. Ако файлът ви е другаде, изпратете го като content_base64 и mssgs ще го хоства.

### Неуспешното качване не проваля съобщението

Файловете се проверяват предварително, но се качват след това. Ако качването се провали, този файл отпада, а останалата част от съобщението се публикува, без грешка: по-добре да загубите файла, отколкото отчета. Ако файлът е важен, проверете дали е пристигнал.

### Файл от командния ред

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

## Подписване на заявки

Уебхук с таен ключ приема само заявки, които доказват, че го знаят, а уебхук, създаден в настолното приложение, винаги има такъв (**Webhook Secret** в настройките му). Подпишете суровото тяло на заявката с HMAC-SHA256 с тайния ключ и изпратете хекс дайджеста с малки букви в хедъра X-Mssgs-Signature като 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
});
```

Приема се и собственият хедър на GitHub X-Hub-Signature-256 , така че уебхук на GitHub със същия таен ключ работи без промени. Подписът няма времеви печат и не пречи прихваната заявка да бъде изпратена отново: истинската тайна остава URL адресът.

## Отговори и грешки

Публикуваното съобщение се връща със своето id и callback_url , с който да го обновите или изтриете в рамките на 30 минути.

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

Когато съобщението има бутони, отговорът съдържа и stream_url : поток на живо с отговорите, реакциите и натисканията на бутони по това съобщение, отворен 10 минути или един час, ако изпратите "sse_event_extended_timeout": true . Вижте [обновления на живо](https://docs.mss.gs/bg/live-updates).

### Статус кодове

| Статус | Кога |
| --- | --- |
| 401 | Уебхукът има таен ключ, а подписът липсва или е грешен. |
| 403 | Този уебхук не може да публикува в този канал. |
| 404 | На този URL адрес няма уебхук. |
| 413 | Заявката е твърде голяма. |
| 429 | Твърде много заявки. Забавете темпото и опитайте отново. |
| 502 | Съобщението не можа да бъде доставено. Опитайте отново. |

### Кодове на грешки

| Код | Значение |
| --- | --- |
| MISSING_CONTENT | Няма какво да се публикува: няма текст, карта или файлове. |
| INVALID_MESSAGE_CONTAINER | message_container не е обект. |
| INVALID_MESSAGE_CONTAINER_TYPE | Типът на картата не е embed_message или system_message . |
| MISSING_MESSAGE_CONTAINER_DESCRIPTION | Картата трябва да има описание, освен ако не е индикатор за зареждане. |
| MISSING_MESSAGE_CONTAINER_LOADER_TEXT | Картата с индикатор за зареждане трябва да има loader_text . |
| INVALID_WEBHOOK_BINDING | Този уебхук не може да публикува в този канал. |
| INVALID_SIGNATURE | Хедърът с подписа липсва или е грешен. |
| REQUEST_BODY_TOO_LARGE | Заявката надвишава лимита за размер. |
| PUBLISH_FAILED | Съобщението не можа да бъде доставено. |
| INVALID_ACTIONS_FORMAT , INVALID_ACTION_MISSING_FIELDS , DUPLICATE_ACTION_ID , INVALID_TRIGGERS_FORMAT , INVALID_TRIGGER_MISSING_ACTION , INVALID_TRIGGER_ACTION_NOT_ALLOWED | Нещо не е наред с бутон. Вижте [бутони](https://docs.mss.gs/bg/buttons). |

### Грешки при файловете

| Код | Значение |
| --- | --- |
| INVALID_ATTACHMENTS_FORMAT | attachments не е списък или някой запис не е обект. |
| TOO_MANY_ATTACHMENTS | Повече от пет файла. |
| MISSING_ATTACHMENT_NAME | Файл няма име. |
| INVALID_ATTACHMENT_NAME | От името не остава нищо използваемо, например .. . |
| MISSING_ATTACHMENT_SOURCE | Нито url , нито content_base64 . |
| AMBIGUOUS_ATTACHMENT_SOURCE | И url , и content_base64 . |
| INVALID_ATTACHMENT_BASE64 | Base64 не може да се декодира. |
| ATTACHMENT_TOO_LARGE | Файл е над 8 MB след декодиране. |
| INVALID_ATTACHMENT_URL | url не е адрес на mssgs. |

## Лимити

| Лимит | Стойност |
| --- | --- |
| Размер на заявката | Около 10 MB |
| Файлове на съобщение | 5, до 8 MB всеки |
| Описание на картата | До 50 000 байта. Над 1000 байта членовете виждат началото и бутон **Show more**. |
| Обновяване на съобщението след публикуване | 30 минути, чрез callback_url |
| Поток на живо за съобщение с бутони | 10 минути или един час при поискване |

Заявките са с ограничена честота. Когато получите 429 , изчакайте, преди да изпратите отново, и обединявайте известията, които идват на вълни, в едно съобщение.

## GitHub, UniFi и App Store Connect

Насочете някоя от тези услуги към URL адрес на уебхук и mssgs ще я разпознае и ще публикува подходяща карта, без да пишете payload. Вижте [интеграции](https://mss.gs/bg/integrations). Те получават отговор {"success": true} и никакъв callback URL.

| Източник | Разпознава се по | Какво публикува |
| --- | --- | --- |
| GitHub | Хедърът x-github-event | Push-ове, pull request-и и рецензии, issues и коментари, клонове и тагове, издания. Поредица от промени по един issue или pull request се събира в една карта. |
| UniFi Protect | User agent protect-alarm-manager | Звънене на вратата, движение, както и хора, превозни средства или пратки, засечени от вашите камери. |
| App Store Connect | Тялото на известията му или хедърът x-apple-signature | Известия от App Store Connect. |

## Продължете нататък