Web Kancaları (Webhooks)

Web kancaları, gityar depolarınızdaki olaylara yanıt veren entegrasyonlar oluşturmanızı sağlar. Bir olay gerçekleştiğinde (push veya sorun oluşturma gibi), gityar yapılandırılmış URL'ye bir HTTP POST payload gönderir.

Web Kancası Oluşturma

Adımlar

1. Depo Ayarları → Web Kancaları gidin
2. "Web Kancası Ekle" tıklayın
3. Web kanca türünü seçin:
   • Gitea - gityar/Gitea örnekleri için
   • Gogs - Gogs örnekleri için
   • Slack - Slack bildirimleri
   • Discord - Discord bildirimleri
   • Dingtalk - Dingtalk bildirimleri
   • Telegram - Telegram botu
   • Microsoft Teams - Teams bildirimleri
   • Özel - Herhangi bir HTTP endpoint
4. Web kanca ayarlarını yapılandırın
5. "Oluştur" tıklayın

Web Kancası Etkinlikleri

Depo Etkinlikleri

• push - Depoya Git push
• create - Branch veya tag oluşturuldu
• delete - Branch veya tag silindi
• fork - Depo fork'landı
• release - Sürüm yayınlandı

Sorun Etkinlikleri

• issues - Sorun açıldı, kapandı, yeniden açıldı
• issue_comment - Sorun üzerinde yorum

Çekme İsteği Etkinlikleri

• pull_request - PR açıldı, kapandı, birleştirildi, senkronize edildi

Wiki Etkinlikleri

• wiki - Wiki sayfası oluşturuldu, düzenlendi, silindi

Web Kancası Yapılandırması

Temel Ayarlar

URL: Web kanca payload'larını alacak endpoint

https://your-server.com/webhook

İçerik Türü: Payload formatı

• application/json - JSON formatı (önerilir)
• application/x-www-form-urlencoded - Form encoded

Secret: Payload doğrulaması için isteğe bağlı secret

Sunucunuz HMAC-SHA256 kullanarak X-Gitea-Signature başlığını doğrulamalıdır.

SSL Doğrulaması: SSL sertifikalarını doğrula

• Production için etkinleştirin
• Sadece test için devre dışı bırakın

HTTP Temel Kimlik Doğrulaması: Kimlik doğrulaması ekleyin

username:password

Trigger Ayarları

Hangi etkinlikler?:

• Sadece push etkinliği - Sadece push'larda tetiklenir
• Her şeyi gönder - Tüm etkinlikler
• Bireysel etkinlikleri seçeyim - Belirli etkinlikleri seçin

Aktif: Web kancasını etkinleştirin veya devre dışı bırakın

Web Kancalarını Test Etme

Manuel Test

1. Web kanca ayarlarına gidin
2. "Test Teslimatı" → "Push" tıklayın
3. Sonuçlar için teslimat geçmişini kontrol edin

Teslimat Geçmişini Görüntüleme

1. Web kanca ayrıntılarını açın
2. Son teslimatların listesini görün
3. Görüntülemek için teslimata tıklayın:
   • İstek başlıkları
   • İstek payload'u
   • Yanıt başlıkları
   • Yanıt gövdesi
   • Yanıt durum kodu
   • Süre

Payload Örnekleri

Push Etkinliği

{
  "secret": "your-secret",
  "ref": "refs/heads/main",
  "before": "6113c5d64f9c8b4e7f2e4a7b3d1c9e5f8a2b4c6d",
  "after": "a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0",
  "commits": [
    {
      "id": "a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0",
      "message": "Yeni özellik ekle",
      "url": "http://localhost:3000/user/repo/commit/a1b2c3d4",
      "author": {
        "name": "John Doe",
        "email": "john@example.com"
      }
    }
  ],
  "repository": {
    "id": 1,
    "name": "my-repo",
    "full_name": "user/my-repo",
    "url": "http://localhost:3000/user/my-repo"
  },
  "pusher": {
    "name": "user",
    "email": "user@example.com"
  }
}

Web Kancası Güvenliği

Payload'ları Doğrulama

Her zaman web kanca imzalarını doğrulayın:

import hmac
import hashlib

def verify_webhook(payload, signature, secret):
    expected = hmac.new(
        secret.encode('utf-8'),
        payload,
        hashlib.sha256
    ).hexdigest()
    
    return hmac.compare_digest(expected, signature)

En İyi Uygulamalar

• ✅ Production'da her zaman HTTPS kullanın
• ✅ Güçlü bir secret ayarlayın
• ✅ İmzaları doğrulayın
• ✅ Payload'ları doğrulayın
• ✅ Hataları düzgün şekilde yönetin
• ✅ Retry mantığı uygulayın
• ✅ Web kanca teslimatlarını loglayın

Yaygın Kullanım Durumları

CI/CD Entegrasyonu

Push'larda build'leri tetikleyin:

from flask import Flask, request
import subprocess

app = Flask(__name__)

@app.route('/webhook', methods=['POST'])
def webhook():
    # İmzayı doğrula
    # Payload'u işle
    
    # Build'i tetikle
    subprocess.run(['./build.sh'])
    
    return 'OK', 200

if __name__ == '__main__':
    app.run(port=5000)

Slack Bildirimleri

Slack kanalına mesaj gönderin:

import requests

def notify_slack(message):
    url = "https://hooks.slack.com/services/YOUR/SLACK/WEBHOOK"
    
    payload = {
        "text": f"Depoya yeni push: {message}"
    }
    
    requests.post(url, json=payload)

Sorun Takibi

Harici sistemlerde bilet oluşturun:

def create_jira_issue(payload):
    # Sorun bilgilerini çıkar
    # Jira'da bilet oluştur
    # gityar'a geri bağla
    pass

Sorun Giderme

Yaygın Sorunlar

Web kanca tetiklenmiyor:

• Web kancanın aktif olduğunu kontrol edin
• Etkinlik trigger'larını doğrulayın
• URL'nin erişilebilir olduğunu kontrol edin

404 Hatası:

• URL'nin doğru olduğunu doğrulayın
• Endpoint'in var olduğundan emin olun
• Routing'i kontrol edin

401/403 Hatası:

• Kimlik doğrulamayı kontrol edin
• Kimlik bilgilerini doğrulayın
• Erişim kontrollerini gözden geçirin

500 Hatası:

• Sunucu loglarını kontrol edin
• Payload işlemeyi doğrulayın
• Hata yönetimini gözden geçirin

Debug İpuçları

• Web kanca teslimat geçmişini kullanın
• Yerel geliştirme için ngrok gibi araçlarla test edin
• Gelen tüm web kancalarını loglayın
• Web kanca test servislerini kullanın

Sonraki Adımlar

• API hakkında bilgi edinin
• Git LFS keşfedin
• Taşıma hakkında okuyun