Wiki

Webhook'lar

Depo başına giden bildirimler (Discord, Slack, Teams, custom): check-in, check-out ve etkinlik özetlerinde. Oluşturma, mesaj biçimi, şablon değişkenleri, SSRF koruması.

Giriş

Bir webhook, bir depoda her olay gerçekleştiğinde harici bir hizmete (Discord, Slack, Microsoft Teams, veya seçtiğiniz bir URL) giden bir bildirim gönderir: bir check-in, bir check-out veya periyodik bir etkinlik özeti. Bir ekibi istemciyi açmadan haberdar tutmanın en basit yoludur: biri iş gönderdiğinde kanalınıza bir mesaj düşer.

Webhook'lar depo başına, masaüstü istemcisinin yönetim panelinde, Webhooks sekmesinde yapılandırılır. Bir deponun birden çok webhook'u olabilir (örneğin tüm ekip için Discord'a bir tane, liderler için özel bir Slack'e bir tane).

Erişim ve roller

Webhook yönetimi depo yöneticilerine ayrılmıştır: herhangi bir depoda bir süper yönetici (admin rolü) veya yönettiği depolarda bir project_admin. Diğer roller bu sekmeyi görmez.

Bilinmesi gereken Webhooks sekmesi çoklu webhook sistemini kullanır (depo başına birden çok kayıt). Tek URL'li eski bir Discord bildirimi uyumluluk için sunucu tarafında hâlâ mevcuttur, ancak bu yeni sekmede gösterilmez: burada anlatılan webhook'ları kullanın.

Webhook oluşturma

Add Webhook formu: Name, URL, Type (discord/slack/teams/custom), Events kutucukları, Enabled anahtarı.

Yönetim panelini açın, depoyu seçin, ardından Webhooks sekmesini açın.
Add Webhook'a tıklayın.
Alanları doldurun, ardından Create.

Alan	Değer
Name	Sonradan tanımak için bir etiket (ör. `Discord équipe`). Zorunlu.
URL	Hedef hizmetin sağladığı webhook URL'si. Zorunlu. Reddedilen URL'ler için Güvenlik bölümüne bakın.
Type	`discord`, `slack`, `teams` veya `custom`.
Events	`checkin`, `checkout`, `activity_summary` arasından bir veya birkaçı. En az biri zorunlu.
Enabled	Etkinleştirme anahtarı (düzenlemede ve listeden görünür).

Discord tarafında URL'yi almak için: Kanal ayarları → Entegrasyonlar → Webhook'lar → Yeni Webhook → Webhook URL'sini Kopyala. Slack tarafında: Slack uygulaması ayarlarında bir Incoming Webhook oluşturun. Teams tarafında: kanalda Bağlayıcılar → Incoming Webhook.

Eğitim: Discord webhook'u

Bu en yaygın durumdur. «URL'yi alma» kısmı tamamen Discord içinde, yalnızca bir kez gerçekleşir.

Discord tarafında: URL'yi alma

Discord'u açın ve sunucunuza gidin. Bildirimleri alacak metin kanalını seçin (veya oluşturun), örneğin #uversion.
Kanal adının üzerine gelin ve dişli simgesine tıklayın («Kanalı Düzenle»).
Soldaki menüde Entegrasyonlar sekmesini açın.
Webhook'lar'a, ardından Yeni Webhook'a tıklayın. Discord bu kanala bağlı olarak otomatik bir tane oluşturur.
Oluşturulan webhook'a tıklayarak açın. Ona bir ad verin (örneğin uVersion) ve hedef kanalın doğru olduğunu doğrulayın. Avatar görseli isteğe bağlıdır.
Webhook URL'sini Kopyala'ya tıklayın. URL şuna benzer: https://discord.com/api/webhooks/123456789/AbCdEf....

Bu URL'yi gizli tutun URL'ye sahip olan herkes kanalınıza mesaj gönderebilir. Onu depoya commit'lemeyin ve herkese açık paylaşmayın. Sızarsa, webhook'u Discord tarafında silin ve yenisini oluşturun.

uVersion tarafında: URL'yi bağlama

Masaüstü istemcisinde yönetim panelini açın, depoyu seçin, ardından Webhooks sekmesini açın.
Add Webhook'a tıklayın.
Name: kendiniz için bir etiket (ör. Discord équipe).
URL: Discord'dan kopyaladığınız URL'yi yapıştırın.
Type: discord seçin (mesajın Discord embed'i olarak biçimlendirilmesi için zorunlu).
Events: istediğiniz olayları işaretleyin, örneğin checkin.
Create'e tıklayın.
Webhook satırında Send test'e tıklayın: birkaç saniye içinde Discord kanalında bir test mesajı görünmelidir.

Test bir HTTP 401 veya 404 koduyla başarısız olursa, URL yanlıştır ya da webhook Discord tarafında silinmiştir: URL'yi yeniden kopyalayın. Test yeşil olmasına rağmen hiçbir şey gelmiyorsa, doğru kanala baktığınızı ve webhook'un Discord'da devre dışı bırakılmadığını doğrulayın.

Türler ve biçimler

Type, uVersion'ın mesajı göndermeden önce nasıl biçimlendireceğini belirler. URL'nin işaret ettiği hizmete uygun olanı seçin, aksi hâlde mesaj bozuk biçimde ulaşır (veya hizmet tarafından reddedilir).

Type	Gönderilen biçim
`discord`	Discord embed'i (başlık, renk, alanlar).
`slack`	Slack yükü (mesaj blokları).
`teams`	Microsoft Teams kartı (MessageCard).
`custom`	Tamamen sizin tanımladığınız JSON gövdesi: Özel webhook'lar bölümüne bakın.

Olaylar

Olay	Tetiklenme koşulu…
`checkin`	Bir kullanıcı depoya bir commit gönderdiğinde.
`checkout`	Bir kullanıcı bir veya birden çok dosyayı kilitlediğinde (check-out).
`activity_summary`	Sunucu zamanlayıcısı periyodik bir etkinlik özeti ürettiğinde (günlük / haftalık).

Yalnızca kanalınızın ihtiyaç duyduğunu işaretleyin. Büyük bir stüdyoda checkout gürültülü olabilir: birçok ekip yalnızca checkin ve activity_summary'yi tutar.

Özel webhook'lar

custom türüyle iki ek alan görünür: Custom Headers (JSON) ve Custom Template (JSON). Bunlar, JSON POST kabul eden herhangi bir hizmeti entegre etmenizi sağlar.

Template

Şablon, gönderilen JSON gövdesidir. uVersion, çift süslü parantez içindeki değişkenleri olayın değerleriyle değiştirir. Örnek:

{"text": "{{event_type}} par {{username}} dans {{repository}}"}

Kullanılabilir değişkenler:

Değişken	İçerik
`{{event_type}}`	Olay türü (`checkin`, `checkout`, `activity_summary`).
`{{repository}}`	Depo adı.
`{{username}}`	Olayı başlatan kullanıcı.
`{{message}}`	Commit mesajı (bir check-in için).
`{{file_count}}`	İlgili dosya sayısı.
`{{commit_hash}}`	Commit karması.
`{{timestamp}}`	Olayın zaman damgası.

Headers

İsteğe eklenecek HTTP başlıklarından oluşan bir JSON nesnesi, örneğin bir kimlik doğrulama belirteci:

{"Authorization": "Bearer VOTRE_JETON"}

Varsayılan olarak {} (başlık yok). Taşımaya ayrılmış başlıklar (host, content-length, transfer-encoding, connection) otomatik olarak kaldırılır ve geçersiz kılınamaz.

Geçerli JSON zorunlu Headers ve Template alanları kaydederken doğrulanır. Geçersiz JSON, kaydetmeyi açık bir mesajla engeller («Invalid JSON in headers» / «… template»). Süslü parantezlerinizi ve tırnaklarınızı kontrol edin.

Test etme, etkinleştirme, silme

« Send test » düğmesine sahip bir webhook satırı ve ideal olarak Discord'da alınan test mesajı.

Listedeki her webhook aşağıdaki eylemleri sunar:

Send test (uçak simgesi): hizmete bir test bildirimi gönderir ve satır içinde bir sonuç gösterir (yeşil onay veya çarpı). Ona güvenmeden önce URL ve türü doğrulamak için yararlıdır.
Anahtar: webhook'u silmeden etkinleştirir / devre dışı bırakır.
Edit: herhangi bir alanı düzenler.
Delete: kalıcı silme (onay istenir).

Test, yanıt gövdesini döndürmez Başarısızlık durumunda uVersion yalnızca hizmetin döndürdüğü HTTP kodunu belirtir (ör. «Webhook returned HTTP 404»), yanıtın içeriğini asla döndürmez. Bu bilinçlidir (Güvenlik bölümüne bakın). Test başarısız olursa önce URL ve türü, ardından hizmet tarafındaki webhook izinlerini kontrol edin.

Güvenlik: SSRF koruması

Bir webhook, bir HTTP isteğinin sunucu tarafından gönderilmesini sağlar. Kötü niyetli bir URL'nin sunucunun iç ağını yoklamak (SSRF saldırısı) için kullanılmasını önlemek amacıyla, uVersion oluşturma, değiştirme ve test sırasında katı bir koruma uygular:

Şema http veya https olmalıdır. Diğer her şema reddedilir.
Ana bilgisayar adı DNS ile çözümlenir ve elde edilen her IP adresi denetlenir. Biri genel olmayan bir adrese işaret ediyorsa webhook reddedilir: loopback, özel ağlar (RFC1918), link-local, broadcast, CGNAT aralığı 100.64.0.0/10, bulut meta verisi 169.254.169.254, ULA / IPv6 link-local ve bunların IPv4-mapped-IPv6 karşılıkları.
HTTP yönlendirmeleri izlenmez (böylece bir iç ana bilgisayara yapılan 307 korumayı atlayamaz).
Yukarı akış yanıt gövdesi istemciye asla döndürülmez (SSRF oracle'ı yok).

Uygulamada: bir webhook URL'si genel bir hizmete işaret etmelidir (Discord, Slack, Teams veya İnternet'ten erişilebilen kendi uç noktanız). localhost, özel bir IP (10.x, 192.168.x, 172.16-31.x) veya dahili bir hizmete giden bir URL, «Webhook URL refused: …» mesajıyla reddedilir.

Sık karşılaşılan tuzaklar

Tür, hizmetle eşleşmiyor

Bir Discord biçimini bir Slack URL'sine (veya tersine) göndermek, bozuk biçimli bir mesaj veya hizmet tarafında bir ret üretir. Type alanı URL ile eşleşmelidir. Şüpheniz varsa bir Send test yapın.

Hiçbir olay işaretlenmemiş

Olayı olmayan bir webhook asla tetiklenmez. Hiçbir olay seçilmediği sürece istemci kaydetmeyi engeller («At least one event is required»).

Dahili URL reddedildi

Kendi makinenizdeki veya LAN'ınızdaki bir hizmete karşı test yaparsanız, SSRF koruması onu reddeder. Webhook hedefi olarak kullanmak için hizmeti genel bir URL'de (veya bir tünelde) yayınlayın.

Unutulmuş devre dışı webhook

Devre dışı bırakılmış bir webhook listede kalır ama hiçbir şey göndermez. Bildirimler sustuysa, URL'den şüphelenmeden önce etkinleştirme anahtarını kontrol edin.