Pubblica messaggi con un webhook

Per iniziare

1. 1

   Crea il webhook

   Nell’app desktop apri Gestisci il server → Webhook della tua community, crea un webhook, scegli i canali in cui può pubblicare e copia l’URL per un canale. Ha questa forma:

   urlCopia

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

2. 2

   Invia un messaggio

   Firma il JSON con il segreto del webhook e invialo in POST. Un webhook creato nell’app desktop ne ha sempre uno: copialo da Segreto del webhook nelle impostazioni del webhook.

   bashCopia

   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

   Leggi la risposta

   La risposta ti dà l’id del messaggio e una callback_url per cambiare il messaggio in seguito.

   jsonCopia

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

Cosa puoi inviare

Un messaggio è la forma breve (testo con un titolo e un colore) oppure una card completa, e in entrambi i casi può avere pulsanti e file. Il nome in cima alla card è sempre il nome del webhook. Nelle impostazioni del webhook decidi anche se può pubblicare immagini e menzionare persone.

Forma breve

Basta per la maggior parte degli avvisi.

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

Una card completa

Invia un message_container per una card con titolo linkato, sottotitolo, markdown, campi e immagini. Tramite un webhook una card accetta type, color, title, title_url, sub_title, description, fields, avatar_url, image_url, image_base64, images e i campi del loader. La pillola di stato, il badge, le statistiche diff e il ragionamento ripiegato sono per le risposte ai comandi. Ogni campo è descritto in card dei messaggi.

jsonCopia

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

Messaggio da CI

Build #1847 riuscita

Tutti i 212 test verdi su main.

Duration

2m 34s

Commit

1a2b3c4

09:12

Pulsanti

Aggiungi un array actions per mettere dei pulsanti sotto il messaggio. Come funzionano è spiegato in pulsanti.

File

Pubblica file veri con un messaggio: un log, un report, uno screenshot. Vengono mostrati come qualsiasi altro allegato, come riga da scaricare oppure inline per immagini, video e audio. Un messaggio con soli file va bene: ometti content e la card.

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

Perché url accetta solo indirizzi mssgs

L’URL di un webhook finisce spesso incollato in altre dashboard. Se trapela, non deve permettere a qualcuno di far scaricare all’app di ogni membro un file da un server scelto da lui. Se il tuo file si trova altrove, invialo come content_base64 e lo ospita mssgs.

Un caricamento fallito non fa fallire il messaggio

I file vengono controllati subito ma caricati dopo. Se un caricamento fallisce, quel file viene tralasciato e il resto del messaggio viene comunque pubblicato, senza errori: meglio perdere il file che perdere il report. Se un file è importante, controlla che sia arrivato.

Un file dalla riga di comando

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

Firmare le richieste

Un webhook con un segreto accetta solo le richieste che dimostrano di conoscerlo, e un webhook creato nell’app desktop ne ha sempre uno (Segreto del webhook nelle sue impostazioni). Firma il body grezzo della richiesta con HMAC-SHA256 usando il segreto e invia il digest esadecimale in minuscolo nell’header X-Mssgs-Signature, come 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
});

Viene accettato anche l’header X-Hub-Signature-256 di GitHub, quindi un webhook GitHub con lo stesso segreto funziona così com’è. La firma non ha un timestamp, quindi non impedisce che una richiesta intercettata venga inviata di nuovo: il segreto che conta resta l’URL.

Risposte ed errori

Un messaggio pubblicato torna indietro con il suo id e una callback_url per aggiornarlo o eliminarlo per 30 minuti.

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

Quando il messaggio ha dei pulsanti, la risposta contiene anche uno stream_url: uno stream live delle risposte, delle reazioni e delle pressioni dei pulsanti su quel messaggio, aperto per 10 minuti, oppure per un’ora se invii "sse_event_extended_timeout": true. Vedi aggiornamenti live.

Status code

Codici di errore

Errori dei file

Limiti

Le richieste hanno un rate limit. Quando ricevi un 429, aspetta prima di inviare di nuovo, e raggruppa in un solo messaggio gli avvisi che arrivano a raffica.

GitHub, UniFi e App Store Connect

Punta uno di questi servizi all’URL di un webhook e mssgs lo riconosce e pubblica una card fatta apposta, senza payload da scrivere. Vedi integrazioni. Questi rispondono con {"success": true} e senza callback URL.