Publikuj wiadomości webhookiem

Szybki start

1. 1

   Utwórz webhook

   W aplikacji desktopowej otwórz w swojej społeczności Manage Server → Webhooks, utwórz webhook, wybierz kanały, na których może publikować, i skopiuj URL dla kanału. Wygląda tak:

   urlKopiuj

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

2. 2

   Wyślij wiadomość

   Podpisz JSON sekretem webhooka i wyślij go POST-em. Webhook utworzony w aplikacji desktopowej zawsze ma sekret: skopiuj go z pola Webhook Secret w ustawieniach webhooka.

   bashKopiuj

   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

   Odczytaj odpowiedź

   Odpowiedź zawiera id wiadomości i callback_url, którym później zmienisz wiadomość.

   jsonKopiuj

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

Co można wysłać

Wiadomość to albo forma skrócona (tekst z tytułem i kolorem), albo pełna karta, a każda z nich może zawierać przyciski i pliki. Nazwa u góry karty to zawsze nazwa samego webhooka. W ustawieniach webhooka decydujesz też, czy może publikować obrazy i oznaczać ludzi.

Forma skrócona

Wystarcza do większości alertów.

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

Pełna karta

Wyślij message_container, aby dostać kartę z tytułem jako linkiem, podtytułem, markdownem, polami i obrazami. Przez webhook karta przyjmuje type, color, title, title_url, sub_title, description, fields, avatar_url, image_url, image_base64, images oraz pola loadera. Pigułka statusu, odznaka, statystyki diffu i zwinięte rozumowanie są zarezerwowane dla odpowiedzi na komendy. Wszystkie pola opisuje strona karty wiadomości.

jsonKopiuj

{
  "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 zakończony sukcesem

Na main przechodzi 212 z 212 testów.

Duration

2m 34s

Commit

1a2b3c4

09:12

Przyciski

Dodaj tablicę actions, aby umieścić przyciski pod wiadomością. Jak działają, opisuje strona przyciski.

Pliki

Publikuj z wiadomością prawdziwe pliki: log, raport, zrzut ekranu. Wyświetlają się jak każdy inny załącznik, jako wiersz do pobrania, a obrazy, wideo i audio bezpośrednio w wiadomości. Wiadomość z samymi plikami też jest w porządku: pomiń content i kartę.

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

Dlaczego url przyjmuje tylko adresy mssgs

URL webhooka często trafia do paneli innych usług. Jeśli wycieknie, nie może pozwolić nikomu sprawić, by aplikacja każdego członka pobierała plik z wybranego przez niego serwera. Jeśli twój plik jest gdzie indziej, wyślij go jako content_base64, a mssgs będzie go hostować.

Nieudane przesłanie pliku nie blokuje wiadomości

Pliki są sprawdzane z góry, ale przesyłane później. Jeśli przesyłanie się nie powiedzie, ten plik zostaje pominięty, a reszta wiadomości i tak zostaje opublikowana, bez błędu: lepiej stracić plik niż raport. Jeśli plik jest ważny, sprawdź, czy dotarł.

Plik z wiersza poleceń

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

Podpisywanie żądań

Webhook z sekretem przyjmuje tylko żądania, które dowodzą, że go znają, a webhook utworzony w aplikacji desktopowej zawsze ma sekret (Webhook Secret w jego ustawieniach). Podpisz surowe body żądania algorytmem HMAC-SHA256 z użyciem sekretu i wyślij digest hex małymi literami w nagłówku X-Mssgs-Signature jako 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
});

Akceptowany jest też własny nagłówek GitHuba X-Hub-Signature-256, więc webhook GitHuba z tym samym sekretem działa bez zmian. Podpis nie zawiera znacznika czasu, więc nie chroni przed ponownym wysłaniem przechwyconego żądania: to URL pozostaje sekretem, który się liczy.

Odpowiedzi i błędy

Opublikowana wiadomość wraca z id i callback_url, którym przez 30 minut możesz ją zaktualizować lub usunąć.

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

Gdy wiadomość ma przyciski, odpowiedź zawiera też stream_url: strumień na żywo z odpowiedziami, reakcjami i naciśnięciami przycisków na tej wiadomości, otwarty przez 10 minut albo godzinę, jeśli wyślesz "sse_event_extended_timeout": true. Zobacz aktualizacje na żywo.

Kody statusu

Kody błędów

Błędy plików

Limity

Żądania mają limit częstotliwości. Gdy dostaniesz 429, odczekaj przed ponownym wysłaniem, a alerty, które przychodzą falami, łącz w jedną wiadomość.

GitHub, UniFi i App Store Connect

Skieruj jedną z tych usług na URL webhooka, a mssgs ją rozpozna i opublikuje porządną kartę, bez pisania payloadu. Zobacz integracje. Te usługi dostają w odpowiedzi {"success": true} i żadnego callback URL.