Wiki

Webhook'lar

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

Giriş

Bir webhook, bir depoda (sunucuda sürüm denetimi yapılan bir proje) 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 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 bir Discord bildirimi uyumluluk için sunucu tarafında da mevcuttur, ancak burada gösterilmez: bu sayfada anlatılan webhook'ları kullanın.

Webhook oluşturma

1. Webhooks sekmesini açma

Yönetim panelinde önce PROJECT satırının seçicisinden depoyu seçin, ardından aynı satırın Webhooks sekmesini açın: bir webhook bir depoya aittir. Hiçbiri olmayan bir depo No webhooks configured gösterir.

2. Formu açma

Sekmenin sağ üstündeki Add Webhook'a tıklayın. Create Webhook penceresi boş olarak açılır.

3. Alanları doldurma

İki alan zorunludur, Name ve URL, ve Events içinde en az bir olay seçilmelidir (bunlar açılır liste değil, tıklanabilir haplardır). Type, URL'nin işaret ettiği hizmetle eşleşmelidir.

Create Webhook penceresi: Name ve URL alanları, Type açılır menüsü (discord, slack, teams, custom) ve checkin seçili Events haplarının sırası.

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	En az biri zorunlu. Pratikte: `checkin` ve `activity_summary`. `checkout` hakkında Olaylar bölümüne bakın.
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 → URL'yi Kopyala, aşağıdaki eğitimde ayrıntılı. Slack tarafında: Slack uygulaması ayarlarında bir Incoming Webhook oluşturun. Teams tarafında: kanalda Bağlayıcılar → Incoming Webhook.

4. Onaylayın, ardından bir test gönderin

Create Webhook'a tıklayın. Webhook listede etkin olarak görünür. Satırında, uçak simgesi Send test'e tıklayın: uVersion hizmete bir test bildirimi gönderir ve satırın sonunda sonucu gösterir, yeşil bir onay ya da döndürülen HTTP koduyla bir çarpı. Şimdi yapın: bu webhook'a güvenmeden önce URL ve türün doğru olduğunu bilmenin tek yolu budur.

Listedeki bir webhook satırı: anahtarı, adı, discord tür rozeti, olay hapları, Send test düğmesi ve yanındaki yeşil sonuç onayı.

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

Yukarıdaki Webhook oluşturma yordamını şu değerlerle uygulayın: Name kendiniz için bir etiket (ör. Discord équipe), URL az önce kopyaladığınız, Type discord (mesajın Discord embed'i olarak gitmesi için zorunlu), Events checkin. Send test ile bitirin: birkaç saniye içinde Discord kanalında bir 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

Sunucu tarafından gerçekten yayılan iki olay vardır:

Olay	Tetiklenme koşulu…
`checkin`	Bir kullanıcı depoya bir commit gönderdiğinde.
`activity_summary`	Sunucu zamanlayıcısı periyodik bir etkinlik özeti ürettiğinde (günlük / haftalık).

checkout: kutu mevcut, olay asla yayılmıyor Form, bir dosyanın kilitlenmesini bildirmeyi amaçlayan üçüncü bir kutu, checkout, sunar (bir kilit, kullanıcının bir dosyayı değiştirdiği sırada o dosyaya koyduğu ayırmadır). Bu bildirilmiş ancak bugüne kadar hiç yayılmamıştır: işaretlemek herhangi bir bildirim tetiklemez. Buna güvenmeyin ve tek seçim olarak kullanmayın: yalnızca bu olay işaretli bir webhook sonsuza dek sessiz kalır.

Yalnızca kanalınızın ihtiyaç duyduğunu işaretleyin. Pratikte, yararlı kombinasyon ekibin çalışma akışı için checkin ve periyodik bir özet için activity_summary'dir.

Ö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` veya `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

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.