Webhook ile mesaj gönder

Hızlı başlangıç

1. 1

   Webhook’u oluştur

   Masaüstü uygulamasında topluluğunun Manage Server → Webhooks bölümünü aç, bir webhook oluştur, mesaj gönderebileceği kanalları seç ve bir kanalın URL’sini kopyala. Şu biçimdedir:

   urlKopyala

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

2. 2

   Mesaj gönder

   JSON’u webhook’un gizli anahtarıyla imzala ve POST et. Masaüstü uygulamasında oluşturulan bir webhook’un her zaman bir gizli anahtarı vardır: onu webhook’un ayarlarındaki Webhook Secret alanından kopyala.

   bashKopyala

   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

   Yanıtı oku

   Yanıt sana mesajın id’sini ve mesajı sonradan değiştirmek için bir callback_url verir.

   jsonKopyala

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

Neler gönderebilirsin

Bir mesaj ya kısa biçimdedir (başlığı ve rengi olan bir metin) ya da tam bir karttır; ikisi de düğme ve dosya taşıyabilir. Kartın üstündeki ad her zaman webhook’un kendi adıdır. Webhook’un ayarlarında ayrıca görsel gönderip gönderemeyeceğine ve kişilerden bahsedip bahsedemeyeceğine de karar verirsin.

Kısa biçim

Çoğu uyarı için yeterli.

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

Tam bir kart

Bağlantılı başlığı, alt başlığı, markdown’ı, alanları ve görselleri olan bir kart için bir message_container gönder. Webhook üzerinden bir kart type, color, title, title_url, sub_title, description, fields, avatar_url, image_url, image_base64, images ve yükleme alanlarını kabul eder. Durum kapsülü, rozet, diff istatistikleri ve katlanmış akıl yürütme komut yanıtları içindir. Tüm alanlar mesaj kartları sayfasında.

jsonKopyala

{
  "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 başarılı

main üzerinde 212 testin hepsi yeşil.

Duration

2m 34s

Commit

1a2b3c4

09:12

Düğmeler

Mesajın altına düğme koymak için bir actions dizisi ekle. Nasıl çalıştıkları düğmeler sayfasında.

Dosyalar

Bir mesajla gerçek dosyalar gönder: bir log, bir rapor, bir ekran görüntüsü. Diğer ekler gibi görünürler: bir indirme satırı olarak ya da görseller, video ve ses için doğrudan mesajın içinde. Yalnızca dosyalardan oluşan bir mesaj da olur: content alanını ve kartı çıkar.

{
  "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 neden yalnızca mssgs adreslerini kabul ediyor

Bir webhook URL’si çoğu zaman başka panolara yapıştırılır. Sızan bir URL, birinin her üyenin uygulamasına kendi seçtiği bir sunucudan dosya çektirmesine izin vermemeli. Dosyan başka bir yerdeyse onu content_base64 olarak gönder, mssgs barındırsın.

Başarısız bir yükleme mesajı başarısız kılmaz

Dosyalar önceden kontrol edilir ama sonradan yüklenir. Bir yükleme başarısız olursa o dosya dışarıda kalır ve mesajın geri kalanı hata vermeden yine gönderilir: dosyayı kaybetmek raporu kaybetmekten iyidir. Bir dosya önemliyse ulaştığını kontrol et.

Komut satırından bir dosya

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

İstekleri imzalama

Gizli anahtarı olan bir webhook yalnızca onu bildiğini kanıtlayan istekleri kabul eder ve masaüstü uygulamasında oluşturulan bir webhook’un her zaman bir gizli anahtarı vardır (ayarlarındaki Webhook Secret). Ham istek gövdesini gizli anahtarla HMAC-SHA256 kullanarak imzala ve küçük harfli hex özeti X-Mssgs-Signature başlığında sha256=<hex> olarak gönder.

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’ın kendi X-Hub-Signature-256 başlığı da kabul edilir, bu yüzden aynı gizli anahtara sahip bir GitHub webhook’u olduğu gibi çalışır. İmzada zaman damgası yoktur, dolayısıyla yakalanmış bir isteğin yeniden gönderilmesini engellemez: asıl önemli sır URL’nin kendisi olarak kalır.

Yanıtlar ve hatalar

Gönderilen bir mesaj, id’si ve onu 30 dakika boyunca güncellemek ya da silmek için bir callback_url ile döner.

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

Mesajda düğmeler varsa yanıtta bir stream_url de bulunur: o mesaja gelen yanıtların, tepkilerin ve düğme basışlarının canlı akışı. 10 dakika, "sse_event_extended_timeout": true gönderirsen bir saat açık kalır. Canlı güncellemeler sayfasına bak.

Durum kodları

Hata kodları

Dosya hataları

Limitler

İstekler hız sınırına tabidir. 429 aldığında yeniden göndermeden önce bekle ve art arda gelen uyarıları tek bir mesajda topla.

GitHub, UniFi ve App Store Connect

Bu servislerden birini bir webhook URL’sine yönlendir; mssgs onu tanır ve sen hiçbir payload yazmadan düzgün bir kart paylaşır. Entegrasyonlar sayfasına bak. Bunlara {"success": true} ile ve callback URL olmadan yanıt verilir.