Postează mesaje cu un webhook

Start rapid

1. 1

   Creează webhook-ul

   În aplicația desktop, deschide în comunitatea ta Manage Server → Webhooks, creează un webhook, alege canalele în care are voie să posteze și copiază URL-ul pentru un canal. Arată așa:

   urlCopiază

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

2. 2

   Trimite un mesaj

   Semnează JSON-ul cu secretul webhook-ului și trimite-l cu POST. Un webhook creat în aplicația desktop are întotdeauna unul: copiază-l din Webhook Secret, în setările webhook-ului.

   bashCopiază

   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

   Citește răspunsul

   Răspunsul îți dă id-ul mesajului și un callback_url cu care poți modifica mesajul mai târziu.

   jsonCopiază

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

Ce poți trimite

Un mesaj este fie forma scurtă (text cu un titlu și o culoare), fie un card complet, iar oricare dintre ele poate avea butoane și fișiere. Numele din partea de sus a cardului este întotdeauna numele webhook-ului. Tot în setările webhook-ului decizi dacă poate posta imagini și menționa oameni.

Forma scurtă

Suficientă pentru majoritatea alertelor.

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

Un card complet

Trimite un message_container pentru un card cu titlu cu link, subtitlu, markdown, câmpuri și imagini. Printr-un webhook, un card acceptă type, color, title, title_url, sub_title, description, fields, avatar_url, image_url, image_base64, images și câmpurile de loader. Eticheta de status, badge-ul, statisticile de diff și raționamentul pliat sunt pentru răspunsurile la comenzi. Toate câmpurile sunt descrise la carduri de mesaj.

jsonCopiază

{
  "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-ul #1847 a trecut

Toate cele 212 teste sunt verzi pe main.

Duration

2m 34s

Commit

1a2b3c4

09:12

Butoane

Adaugă un array actions ca să pui butoane sub mesaj. Cum funcționează afli la butoane.

Fișiere

Postează fișiere reale împreună cu un mesaj: un log, un raport, o captură de ecran. Apar ca orice alt atașament, ca rând de descărcare sau direct în mesaj pentru imagini, video și audio. Un mesaj doar cu fișiere este în regulă: lasă deoparte content și cardul.

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

De ce url acceptă doar adrese mssgs

Un URL de webhook ajunge adesea lipit în alte dashboard-uri. Dacă scapă, nu trebuie să-i permită cuiva să facă aplicația fiecărui membru să descarce un fișier de pe un server ales de el. Dacă fișierul tău se află în altă parte, trimite-l ca content_base64, iar mssgs îl găzduiește.

O încărcare eșuată nu blochează mesajul

Fișierele sunt verificate de la început, dar încărcate după aceea. Dacă o încărcare eșuează, fișierul respectiv este omis, iar restul mesajului se postează oricum, fără eroare: e mai bine să pierzi fișierul decât raportul. Dacă un fișier contează, verifică dacă a ajuns.

Un fișier din linia de comandă

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

Semnarea cererilor

Un webhook cu secret acceptă doar cereri care dovedesc că îl cunosc, iar un webhook creat în aplicația desktop are întotdeauna unul (Webhook Secret în setările lui). Semnează corpul brut al cererii cu HMAC-SHA256 folosind secretul și trimite digestul hex cu litere mici în antetul X-Mssgs-Signature, sub forma 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
});

Este acceptat și antetul propriu al GitHub, X-Hub-Signature-256, așa că un webhook GitHub cu același secret funcționează ca atare. Semnătura nu are timestamp, deci nu împiedică retrimiterea unei cereri interceptate: URL-ul rămâne secretul care contează.

Răspunsuri și erori

Un mesaj postat se întoarce cu id-ul lui și un callback_url cu care îl poți actualiza sau șterge timp de 30 de minute.

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

Când mesajul are butoane, răspunsul conține și un stream_url: un flux live cu răspunsurile, reacțiile și apăsările de butoane de pe acel mesaj, deschis 10 minute sau o oră dacă trimiți "sse_event_extended_timeout": true. Vezi actualizări live.

Coduri de status

Coduri de eroare

Erori de fișiere

Limite

Cererile au o limită de frecvență. Când primești un 429, așteaptă înainte să trimiți din nou și grupează alertele care vin în rafale într-un singur mesaj.

GitHub, UniFi și App Store Connect

Îndreaptă unul dintre aceste servicii spre un URL de webhook, iar mssgs îl recunoaște și postează un card ca lumea, fără să scrii vreun payload. Vezi integrări. Acestea primesc ca răspuns {"success": true} și niciun URL de callback.