Posta meddelanden med en webhook

Snabbstart

1. 1

   Skapa webhooken

   Öppna Hantera community → Webhooks för din community i skrivbordsappen, skapa en webhook, välj vilka kanaler den får posta i och kopiera URL:en för en kanal. Den ser ut så här:

   urlKopiera

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

2. 2

   Skicka ett meddelande

   Signera JSON:en med webhookens hemlighet och gör en POST med den. En webhook som du skapar i skrivbordsappen har alltid en: kopiera den under Webhook-hemlighet i webhookens inställningar.

   bashKopiera

   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

   Läs svaret

   Svaret ger dig meddelandets id och en callback_url som ändrar meddelandet senare.

   jsonKopiera

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

Vad du kan skicka

Ett meddelande är antingen den korta formen (text med rubrik och färg) eller ett helt kort, och båda kan ha knappar och filer. Namnet högst upp på kortet är alltid webhookens eget namn. I webhookens inställningar bestämmer du också om den får posta bilder och nämna personer.

Kort form

Räcker för de flesta larm.

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

Ett helt kort

Skicka en message_container för ett kort med länkad rubrik, underrubrik, markdown, fält och bilder. Via en webhook tar ett kort emot type, color, title, title_url, sub_title, description, fields, avatar_url, image_url, image_base64, images och laddningsfälten. Statuspillen, märket, diff-statistiken och det hopfällda resonemanget är till för kommandosvar. Alla fält finns under meddelandekort.

jsonKopiera

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

Meddelande från CI

Bygge #1847 lyckades

Alla 212 tester gröna på main.

Duration

2m 34s

Commit

1a2b3c4

09:12

Knappar

Lägg till en actions-array för att sätta knappar under meddelandet. Hur de fungerar står under knappar.

Filer

Posta riktiga filer med ett meddelande: en logg, en rapport, en skärmbild. De visas som vilken bilaga som helst, som en nedladdningsrad eller inbäddade för bilder, video och ljud. Ett meddelande med bara filer går bra: utelämna content och kortet.

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

Varför url bara tar emot mssgs-adresser

En webhook-URL hamnar ofta inklistrad i andra dashboards. En URL som har läckt får inte kunna användas för att få varje medlems app att hämta en fil från en server som någon annan har valt. Ligger din fil någon annanstans skickar du den som content_base64, så hostar mssgs den.

En misslyckad uppladdning stoppar inte meddelandet

Filerna kontrolleras direkt men laddas upp efteråt. Misslyckas en uppladdning utelämnas den filen och resten av meddelandet postas ändå, utan något fel: hellre förlora filen än rapporten. Är en fil viktig bör du kontrollera att den kom fram.

En fil från kommandoraden

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

Signera anrop

En webhook med en hemlighet tar bara emot anrop som bevisar att de känner till den, och en webhook som du skapar i skrivbordsappen har alltid en (Webhook-hemlighet i dess inställningar). Signera den råa bodyn i anropet med HMAC-SHA256 och hemligheten, och skicka hex-digesten i gemener i headern X-Mssgs-Signature som 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
});

GitHubs egen header X-Hub-Signature-256 accepteras också, så en GitHub-webhook med samma hemlighet fungerar som den är. Signaturen har ingen tidsstämpel, så den hindrar inte att ett uppsnappat anrop skickas igen: det är fortfarande URL:en som är den hemlighet som räknas.

Svar och fel

Ett meddelande som har postats kommer tillbaka med sitt id och en callback_url som uppdaterar eller raderar det i 30 minuter.

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

När meddelandet har knappar innehåller svaret också en stream_url: en liveström av svaren, reaktionerna och knapptrycken på meddelandet, öppen i 10 minuter, eller en timme när du skickar "sse_event_extended_timeout": true. Se liveuppdateringar.

Statuskoder

Felkoder

Filfel

Gränser

Anropen är hastighetsbegränsade. När du får en 429 väntar du innan du skickar igen, och samlar larm som kommer i skurar i ett enda meddelande.

GitHub, UniFi och App Store Connect

Peka en av de här tjänsterna mot en webhook-URL så känner mssgs igen den och postar ett ordentligt kort, utan någon payload att skriva. Se integrationer. De här svarar med {"success": true} och ingen callback-URL.