Надсилайте повідомлення через вебхук

Швидкий старт

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

Повідомлення від CI

Збірка #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 із цим секретом і надішліть hex-дайджест у нижньому регістрі в заголовку 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.