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

Бърз старт

1. 1

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

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

   urlКопиране

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

2. 2

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

   Подпишете 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"

3. 3

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

   Отговорът ви дава 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-..."
   }

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

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

Кратка форма

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

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

Пълна карта

Изпратете message_container за карта със заглавие с линк, подзаглавие, markdown, полета и изображения. Чрез уебхук картата приема type, color, title, title_url, sub_title, description, fields, avatar_url, image_url, image_base64, images и полетата за индикатор за зареждане. Етикетът за статус, значката, статистиката на diff и сгънатите разсъждения са за отговори на команди. Всички полета са описани в карти на съобщения.

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

#deploys

Message from CI

Build #1847 е успешен

Всички 212 теста са зелени на main.

Duration

2m 34s

Commit

1a2b3c4

09:12

Бутони

Добавете масив actions, за да поставите бутони под съобщението. Как работят, е описано в бутони.

Файлове

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

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

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

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

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

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

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

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

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 минути.

{
  "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/1.1 200 OK
Content-Type: application/json

{ "error": "ATTACHMENT_TOO_LARGE" }

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. Вижте обновления на живо.

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

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

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

Лимити

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

GitHub, UniFi и App Store Connect

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