Δημοσίευσε μηνύματα με webhook

Γρήγορη εκκίνηση

1. 1

   Δημιούργησε το webhook

   Στην εφαρμογή για υπολογιστή, άνοιξε στην κοινότητά σου Manage Server → Webhooks, δημιούργησε ένα webhook, διάλεξε τα κανάλια όπου μπορεί να δημοσιεύει και αντίγραψε το URL για ένα κανάλι. Έχει αυτή τη μορφή:

   urlΑντιγραφή

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

2. 2

   Στείλε ένα μήνυμα

   Υπόγραψε το JSON με το μυστικό του webhook και στείλε το με POST. Ένα webhook που φτιάχτηκε στην εφαρμογή για υπολογιστή έχει πάντα μυστικό: αντίγραψέ το από το Webhook Secret στις ρυθμίσεις του webhook.

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

Τι μπορείς να στείλεις

Ένα μήνυμα είναι είτε η σύντομη μορφή (κείμενο με τίτλο και χρώμα) είτε μια πλήρης κάρτα, και οποιοδήποτε από τα δύο μπορεί να έχει κουμπιά και αρχεία. Το όνομα στην κορυφή της κάρτας είναι πάντα το όνομα του ίδιου του webhook. Στις ρυθμίσεις του webhook αποφασίζεις επίσης αν μπορεί να δημοσιεύει εικόνες και να κάνει mention σε άτομα.

Σύντομη μορφή

Αρκεί για τις περισσότερες ειδοποιήσεις.

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

Πλήρης κάρτα

Στείλε ένα message_container για κάρτα με τίτλο που είναι σύνδεσμος, υπότιτλο, markdown, πεδία και εικόνες. Μέσω webhook μια κάρτα δέχεται type, color, title, title_url, sub_title, description, fields, avatar_url, image_url, image_base64, images και τα πεδία του loader. Η ένδειξη κατάστασης, το badge, τα στατιστικά 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

Message from CI

Το build #1847 πέρασε

Και τα 212 τεστ πράσινα στο main.

Duration

2m 34s

Commit

1a2b3c4

09:12

Κουμπιά

Πρόσθεσε έναν πίνακα actions για να βάλεις κουμπιά κάτω από το μήνυμα. Πώς λειτουργούν θα το βρεις στη σελίδα κουμπιά.

Αρχεία

Δημοσίευσε πραγματικά αρχεία μαζί με ένα μήνυμα: ένα log, μια αναφορά, ένα στιγμιότυπο οθόνης. Εμφανίζονται όπως κάθε άλλο συνημμένο, ως γραμμή λήψης, ή μέσα στο μήνυμα για εικόνες, βίντεο και ήχο. Ένα μήνυμα μόνο με αρχεία είναι εντάξει: παράλειψε το 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 webhook συχνά καταλήγει επικολλημένο σε άλλα dashboards. Αν διαρρεύσει, δεν πρέπει να επιτρέπει σε κάποιον να βάλει την εφαρμογή κάθε μέλους να κατεβάζει ένα αρχείο από έναν server της επιλογής του. Αν το αρχείο σου βρίσκεται αλλού, στείλε το ως 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 @-

Υπογραφή αιτημάτων

Ένα webhook με μυστικό δέχεται μόνο αιτήματα που αποδεικνύουν ότι το γνωρίζουν, και ένα webhook που φτιάχτηκε στην εφαρμογή για υπολογιστή έχει πάντα μυστικό (Webhook Secret στις ρυθμίσεις του). Υπόγραψε το ακατέργαστο σώμα του αιτήματος με HMAC-SHA256 χρησιμοποιώντας το μυστικό και στείλε το hex digest με πεζά γράμματα στην κεφαλίδα 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, οπότε ένα webhook του 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 webhook και το mssgs την αναγνωρίζει και δημοσιεύει μια κανονική κάρτα, χωρίς να γράψεις payload. Δες τις ενσωματώσεις. Αυτές παίρνουν ως απάντηση {"success": true} χωρίς callback URL.