Uygulama webhook'ları

Uygulama webhook'u, CI runner'ının, izleme aracının veya harici bir servisin bir GameVox kanalına mesaj bırakmak için POST edebileceği kanal başına bir URL'dir. Gateway oturumu gerekmez. Mesajlar, botun avatarı ve kullanıcı adıyla bot kullanıcın olarak gönderilir.

Sınırlar

Uygulama başına 50 webhook.
Ad: 1–80 karakter.
İçerik: mesaj başına 1–4000 karakter.
Bir webhook = bir kanal. Webhook oluşturmak, kanalın bulunduğu sunucuda manage_server izni gerektirir.

Token biçimi

WH.{8 karakterlik önek}.{base64 rastgele}

örnek: WH.aB7xZ2k1.q9F7v1NkN3J2Wm8L6PpV5cU0Yr1zQbXa

Tam token, oluşturma sırasında yalnızca bir kez gösterilir. Biz yalnızca bcrypt hash'ini ve gösterim için önekiyle son 4 karakterini saklarız. Bir token'ı kaybedersen webhook'u sil ve yenisini oluştur.

Webhook oluşturma (portal)

Uygulamanı aç → Webhook'lar sekmesi → Yeni Webhook. Yönetebildiğin bir sunucu seç, bir kanal seç, bir ad ver. Gösterim penceresi tam token'ı ve yapıştırmaya hazır çalıştırma URL'sini gösterir. Kapatmadan önce kopyala; portal onu bir daha asla göstermez.

Endpoint'ler

İki kimlik doğrulama modu: yönetim için bot token'ı, çalıştırma için URL token'ı.

Bot token'ı ile kimlik doğrulama (yönetim)

GET    /channels/{channel.id}/webhooks
POST   /channels/{channel.id}/webhooks
GET    /guilds/{guild.id}/webhooks
GET    /webhooks/{webhook.id}
PATCH  /webhooks/{webhook.id}
DELETE /webhooks/{webhook.id}

URL token'ı ile kimlik doğrulama (çalıştırma + düzenleme)

POST   /webhooks/{webhook.id}/{token}
GET    /webhooks/{webhook.id}/{token}
PATCH  /webhooks/{webhook.id}/{token}
DELETE /webhooks/{webhook.id}/{token}
PATCH  /webhooks/{webhook.id}/{token}/messages/{message.id}
DELETE /webhooks/{webhook.id}/{token}/messages/{message.id}

URL token'lı route'larda Authorization header'ı yoktur. URL yolundaki token kimlik doğrulamanın ta kendisidir. URL'yi bir secret gibi koru.

Çalıştırma isteği

JSON gövdesi:

POST https://api.gamevox.com/webhooks/{webhook.id}/{token}
Content-Type: application/json

{
  "content": "#4811 numaralı build production'da başarılı oldu.",
  "embeds": [
    {
      "title": "CI yeşil",
      "url": "https://ci.example.com/builds/4811",
      "description": "42 test, 0 hata.",
      "color": 3066993
    }
  ]
}

multipart/form-data gövdesi (ekler için):

Content-Type: multipart/form-data; boundary=xyz

--xyz
Content-Disposition: form-data; name="payload_json"

{ "content": "Ekran görüntüsüne bak", "embeds": [ ... ] }
--xyz
Content-Disposition: form-data; name="files[0]"; filename="crash.png"
Content-Type: image/png

...binary...
--xyz--

Yanıt (iki içerik türü için de):

{
  "id": "1199283740192847400",
  "channel_id": "1199283740192847000",
  "content": "#4811 numaralı build production'da başarılı oldu.",
  "embeds": [ ... ],
  "attachments": [ ... ],
  "timestamp": "2026-05-21T15:42:09Z"
}

Neler destekleniyor

İçerik: düz metin, 1–4000 karakter.
Embed'ler: tam Discord embed biçimi (title, description, url, color, timestamp, footer, image, thumbnail, author, fields). Mesaj başına birden fazla embed kullanılabilir.
Ekler: dosyaları bir payload_json parçasıyla birlikte multipart/form-data üzerinden yükle; yanıt CDN URL'lerini içerir.
Yanıt hedefleme: payload_json içinde message_reference geçir.
?wait=true: örtük; yanıt her zaman çözümlenmiş mesajdır.
Düzenleme / silme: /webhooks/{id}/{token}/messages/{message.id} üzerindeki PATCH / DELETE Discord'u yansıtır.
Kullanıcı adı / avatar geçersiz kılma: desteklenmiyor. Mesajlar her zaman uygulamanın bot kullanıcısı olarak gönderilir.

Hatalar

401: token eksik, bozuk veya eşleşmiyor.
404: webhook silinmiş ya da ID mevcut değil.
400: content boş ve embed/ek yok ya da content 4000 karakterden uzun.
405: bu route'ta desteklenmeyen HTTP metodu.
413: ek, dosya başına boyut sınırını aşıyor.

Yenileme

v1'de yerinde yenileme endpoint'i yok. Webhook'u sil ve yenisini oluştur. Eski token silme anında çalışmayı durdurur (çalıştırma yolu soft delete ile silinmiş satırları hariç tutar).

Discord'dan farklar

Webhook'lar bir sunucu yöneticisine değil, uygulamaya aittir. Kanalı silmek webhook satırını silmez; sonraki çalıştırma, aramadaki kanal join'inden dolayı 404 döndürür.
İstek başına username / avatar_url geçersiz kılma yok. Kimlik bot kullanıcısına sabittir.
Kanal başına webhook sınırı uygulanmaz; sınır uygulama başınadır (50).
Kimlik doğrulama bcrypt ile yapılır, bu yüzden token karşılaştırması bilerek yavaştır. Endpoint'i sıkı döngülerde art arda çağırıp yorma.
Kendi barındırdığın sunucular: webhook'lar kendi barındırılan sunuculara yönlendirilmez. Tüm webhook endpoint'leri kendi barındırılan guild hedefleri için 404 döndürür. Bkz. Kendi barındırdığın sunucu dokümanları.

← Dokümanlara dön