Публикуйте сообщения через вебхук

Быстрый старт

1. 1

   Создайте вебхук

   В настольном приложении откройте в своём сообществе Управление сервером → Вебхуки, создайте вебхук, выберите каналы, в которые он может публиковать, и скопируйте URL для нужного канала. Он выглядит так:

   urlКопировать

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

2. 2

   Отправьте сообщение

   Подпишите JSON секретом вебхука и отправьте его методом POST. У вебхука, созданного в настольном приложении, секрет есть всегда: скопируйте его из поля Секрет вебхука в настройках вебхука.

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

Подпись запросов

Вебхук с секретом принимает только те запросы, которые доказывают, что знают его, а у вебхука, созданного в настольном приложении, секрет есть всегда (Секрет вебхука в его настройках). Подпишите необработанное тело запроса с помощью 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.