Webhook Nedir ve Nasıl Entegre Edilir?

Webhook nedir sorusunun en kısa cevabı şu: bir sistemde bir olay gerçekleştiğinde, o sistemin senin belirlediğin bir URL'e otomatik olarak HTTP isteği göndermesidir. Yani sürekli "Yeni bir şey oldu mu?" diye sormak yerine, olay olduğunda karşı taraf seni arar. Bu küçük tersine çevirme, modern entegrasyonların belkemiğini oluşturur: ödeme sağlayıcıları, Git platformları, Discord, e-posta servisleri ve neredeyse tüm SaaS ürünleri webhook ile çalışır.

Polling ile Webhook arasındaki fark

Polling (yoklama) modelinde, senin uygulaman belirli aralıklarla karşı API'ye gidip "değişen bir şey var mı?" diye sorar. Çoğu zaman cevap "hayır" olur, yani isteklerin büyük kısmı boşa gider. Dakikada bir sorsan bile, olay ile haberin olması arasında ortalama 30 saniye gecikme oluşur.

Webhook modelinde ise olay tabanlı çalışırsın: bir şey değiştiğinde karşı taraf anında senin endpoint'ine veri yollar. Avantajları net:

• Gerçek zamanlılık: olay olur olmaz haber alırsın, gecikme saniyeler değil milisaniyeler düzeyindedir.
• Verimlilik: boşa giden binlerce istek yerine yalnızca gerçek olaylar için trafik üretilir.
• Ölçeklenebilirlik: sunucun gereksiz sorgularla yorulmaz, rate limit'lere takılmazsın.

Polling'in hâlâ yeri vardır: karşı taraf webhook sunmuyorsa ya da güvenilir teslimat garantisi şartsa. Ama seçim hakkın varsa, olay tabanlı yaklaşım neredeyse her zaman daha temizdir.

Bir webhook isteği neye benzer?

Webhook isteği aslında sıradan bir HTTP POST isteğidir. Gönderen sistem, olayın detaylarını çoğunlukla JSON gövdesinde taşır. Örneğin bir ödeme onayı şuna benzeyebilir:

POST /webhooks/payment HTTP/1.1
Host: senin-siten.com
Content-Type: application/json
X-Signature: t=1719500000,v1=4a9f...c2

{
  "event": "payment.succeeded",
  "data": {
    "id": "pay_8sK2",
    "amount": 4900,
    "currency": "TRY",
    "customer": "cus_12"
  }
}

Senin tarafın bu isteği alır, gövdeyi okur, event tipine göre bir iş yapar (siparişi onaylar, e-posta yollar, kullanıcıya rol verir) ve karşı tarafa hızlıca 200 OK döner. Burada kritik nokta: yanıtı hızlı dön. Ağır işleri (rapor üretmek, dış API çağırmak) bir kuyruğa at, webhook'u beklemede tutma.

Laravel ile webhook alıcı kurmak

Pratikte bir webhook endpoint'i yazmak çok basittir. Laravel ile bir rota ve controller yeterli:

// routes/web.php
Route::post('/webhooks/payment', [WebhookController::class, 'handle'])
    ->withoutMiddleware([VerifyCsrfToken::class]);

Dikkat: webhook'lar dış sistemlerden gelir, oturum çerezi taşımazlar; bu yüzden CSRF korumasını bu rotadan çıkarmak gerekir. Controller tarafında olayı işleriz:

public function handle(Request $request)
{
    $payload = $request->all();

    if ($payload['event'] === 'payment.succeeded') {
        ProcessPayment::dispatch($payload['data']);
    }

    return response()->json(['ok' => true]);
}

Burada ProcessPayment::dispatch(...) ile işi bir queue job'a devrediyoruz; böylece controller anında yanıt döner, ağır iş arka planda yürür.

İmza doğrulama: webhook güvenliğinin kalbi

Webhook URL'in herkese açık olduğu için, kötü niyetli birinin sahte istek göndermesini engellemen gerekir. Çoğu sağlayıcı, gövdeyi paylaşılan bir gizli anahtarla HMAC imzalar ve imzayı bir header'da (ör. X-Signature) yollar. Sen de aynı anahtarla imzayı yeniden hesaplayıp karşılaştırırsın:

$signature = $request->header('X-Signature');
$expected  = hash_hmac('sha256', $request->getContent(), $secret);

if (! hash_equals($expected, $signature)) {
    abort(403, 'Geçersiz imza');
}

Kritik detay: imzayı ham gövde (getContent()) üzerinden hesapla, parse edilmiş diziden değil; çünkü JSON'u yeniden serileştirmek byte düzeyinde farklar yaratabilir. Ayrıca hash_equals() kullan, çünkü == zamanlama saldırılarına açıktır.

Güvenilirlik: tekrar denemeler ve idempotency

Gerçek dünyada her şey her zaman yolunda gitmez. Sunucun bir an cevap veremezse, çoğu sağlayıcı isteği tekrar dener. Bu da aynı olayın birden çok kez gelebileceği anlamına gelir. Bu yüzden işleyiciler idempotent olmalı:

• Her olayın benzersiz bir id alanı vardır; bunu kaydet.
• Aynı id tekrar gelirse, işi tekrar yapma, sadece 200 dön.
• Hızlı 2xx dön; yavaş yanıt sağlayıcının seni başarısız sayıp gereksiz tekrar denemesine yol açar.

Geliştirme aşamasında webhook'ları test etmek için ngrok gibi bir tünel aracıyla yerel sunucunu dışarı açabilir, sağlayıcının panelinden test olayları tetikleyebilirsin.

Sık Sorulan Sorular

Webhook ile API arasındaki fark nedir?

API genellikle senin istek başlattığın, "çek" (pull) modelidir: sen sorarsın, cevap alırsın. Webhook ise "it" (push) modelidir: olay olduğunda karşı taraf sana veri gönderir. Çoğu entegrasyon ikisini birlikte kullanır.

Webhook URL'imi nasıl güvende tutarım?

Mutlaka HTTPS kullan, gelen her isteğin imzasını doğrula, mümkünse sağlayıcının IP aralığını allowlist'e ekle ve gizli anahtarı koda değil ortam değişkenine (.env) koy.

Webhook gelmezse ne yaparım?

Önce sağlayıcının teslimat günlüklerine bak; çoğu, başarısız denemeleri ve dönen HTTP kodunu gösterir. Endpoint'inin gerçekten 200 döndüğünden, ham gövdeyi loglayarak emin ol ve gerekirse olayı panelden elle yeniden gönder.

Olay tabanlı bir entegrasyona mı ihtiyacın var? Ödeme, Discord, Git ya da kendi sistemlerin için güvenli webhook akışları kurmana yardımcı olabilirim. Benimle iletişime geç ve projeni konuşalım.