Webhook Nedir? API Entegrasyonunda Nasıl Kullanılır?

Webhook nedir sorusunun kısa cevabı: bir sistemde bir olay gerçekleştiğinde (ödeme alındı, kargo teslim edildi, sipariş iptal edildi) o sistemin sizin belirlediğiniz bir adrese kendiliğinden HTTP isteği göndermesidir. Normal bir API’de soruyu siz sorarsınız; webhook’ta haber size gelir. Bu fark küçük görünür ama entegrasyonun maliyetini, hızını ve güvenlik yüzeyini baştan sona değiştirir. Bu yazıda webhook’un nasıl çalıştığını, nerede kullanıldığını, doğru kurulan bir webhook alıcısının nelere dikkat etmesi gerektiğini ve kendi sisteminiz başkalarına webhook gönderecekse neyi baştan tasarlamanız gerektiğini anlatıyoruz. Özel yazılım projelerinde entegrasyon katmanını kurarken izlediğimiz kurallar da bunlar.

Webhook ile API arasındaki fark nedir?

İkisi de HTTP üzerinden konuşur, fark yönde ve zamanlamadadır. API’de istemci sizsiniz: “Bu siparişin ödemesi geldi mi?” diye sorarsınız, karşı taraf o anki durumu söyler. Cevabı öğrenmek için ya kullanıcı bir düğmeye basar ya da sisteminiz belirli aralıklarla aynı soruyu tekrar sorar; buna polling denir. Webhook’ta ise siz bir adres verirsiniz (“ödeme gelince şuraya haber ver”), olay olduğunda karşı sistem o adrese bir POST isteği gönderir. Siz sormazsınız, dinlersiniz. API entegrasyonu nedir yazısında genel kavramları anlattık; bu yazı yalnızca webhook tarafını ele alıyor.

Polling ile webhook birbirinin rakibi değil, tamamlayıcısıdır. Olay sık ve anlık tepki önemliyse (ödeme onayı, mesaj geldi bildirimi) webhook doğru araçtır: her beş saniyede bir “geldi mi?” diye soran bir sistem hem boş yere istek üretir hem de ortalama iki buçuk saniye geç kalır. Olay seyrek ve karşı taraf webhook sunmuyorsa polling tek seçenektir; muhasebe programlarının çoğunda durum budur ve bunu muhasebe programı entegrasyonu yazısında ayrıca anlattık.

Webhook nasıl çalışır? Adım adım

• Sisteminizde herkese açık bir HTTPS adresi açarsınız: örneğin /api/webhooks/payment. Bu adres yalnızca POST kabul eder ve hiçbir oturum beklemez.
• Bu adresi sağlayıcının paneline ya da API’sine kaydedersiniz; sağlayıcı size bir gizli anahtar (secret) verir.
• Olay gerçekleştiğinde sağlayıcı, olayın türünü ve verisini JSON olarak bu adrese gönderir; isteğin başlığında gizli anahtarla üretilmiş bir imza bulunur.
• Sunucunuz imzayı doğrular, olayı kaydeder, sağlayıcıya hızlıca 200 döner ve asıl işi (siparişi “ödendi” yapmak, e-posta göndermek) ayrıca yapar.
• Sunucunuz 200 dönmezse ya da geç dönerse sağlayıcı aynı olayı artan aralıklarla yeniden gönderir; bu yüzden aynı olay birden fazla kez gelebilir.

Webhook nerede kullanılır?

Türkiye’deki kurumsal projelerde webhook’un en çok karşımıza çıktığı yerler ödeme, kargo, pazaryeri ve mesajlaşma entegrasyonlarıdır. Ödeme entegrasyonunda siparişi “ödendi” yapan şey kullanıcının gördüğü başarı ekranı değil, sağlayıcıdan gelen ve doğrulanan webhook’tur. Kargo entegrasyonunda teslimat durumu değiştikçe (dağıtımda, teslim edildi, iade) kargo firması size haber verir ve müşteri sayfanız sormadan güncellenir. Pazaryeri entegrasyonunda yeni sipariş ve iptal bildirimleri, WhatsApp Business API tarafında ise gelen mesajlar ve teslim raporları webhook ile ulaşır. Ortak nokta şudur: olay sizin dışınızda, başka bir sistemde olur ve siz onun zamanlamasını kontrol edemezsiniz.

Webhook’un ilk kuralı: webhook bir bildirimdir, gerçeğin kaynağı değildir. Para gerçekten alındı mı, sipariş gerçekten iptal mi; şüpheye düştüğünüzde doğrulamanın yolu olay kimliğiyle sağlayıcının API’sine sormaktır. İyi bir alıcı webhook’a güvenir ama ona bağımlı kalmaz.

Webhook güvenliği: imza doğrulama ve tekrar gelen olaylar

Webhook adresi tanımı gereği herkese açıktır; adresi bilen herkes oraya “ödeme alındı” diyen sahte bir istek gönderebilir. Bu yüzden her sağlayıcı isteği gizli anahtarla imzalar ve siz bu imzayı ham gövde üzerinden yeniden hesaplayıp karşılaştırırsınız. İki klasik hata vardır: gövdeyi önce JSON’a çevirip sonra imzalamak (boşluklar ve alan sırası değiştiği için imza tutmaz) ve karşılaştırmayı basit eşitlikle yapmak (zamanlama saldırısına açıktır). İkinci büyük konu tekrar gelen olaylardır: sağlayıcı 200 alamazsa aynı olayı yeniden gönderir; iş mantığınız olay kimliğine göre tekil değilse aynı sipariş için iki kez stok düşer ya da iki kez e-posta gider. Aşağıdaki Next.js route handler üç kuralı birden uyguluyor: ham gövde üzerinden sabit süreli imza karşılaştırması, olay kimliğiyle tekillik ve ağır işi kuyruğa atıp sağlayıcıya hızlı cevap.

// app/api/webhooks/payment/route.ts
import { createHmac, timingSafeEqual } from 'node:crypto';
import { NextResponse } from 'next/server';

export async function POST(req: Request) {
  // İmza HAM gövde üzerinden hesaplanır; önce JSON.parse yapılmaz.
  const raw = await req.text();
  const received = req.headers.get('x-signature') ?? '';
  const expected = createHmac('sha256', process.env.PAYMENT_WEBHOOK_SECRET!)
    .update(raw)
    .digest('hex');

  // Sabit süreli karşılaştırma: zamanlama saldırısını engeller.
  if (
    received.length !== expected.length ||
    !timingSafeEqual(Buffer.from(received), Buffer.from(expected))
  ) {
    return new NextResponse('invalid signature', { status: 401 });
  }

  const event = JSON.parse(raw) as { id: string; type: string; data: unknown };

  // Tekillik: aynı olay ikinci kez gelirse iş mantığı tekrar çalışmaz.
  const isNew = await db.webhookEvents.insertIfAbsent({
    id: event.id,
    type: event.type,
    payload: raw,
    receivedAt: new Date(),
  });
  if (!isNew) return NextResponse.json({ ok: true, duplicate: true });

  // Ağır iş (stok, e-posta, fatura) kuyrukta; sağlayıcıya hızlı 200.
  await queue.enqueue('process-webhook', { eventId: event.id });
  return NextResponse.json({ ok: true });
}

Olayın ham hâlini saklamak boş bir titizlik değildir. Kuyruktaki iş hata verdiğinde kaydı tekrar işleyebilirsiniz; sağlayıcıyla “bu olay geldi mi, gelmedi mi” tartışmasında kanıtınız olur; ve yeni bir alanı desteklemeye başladığınızda geçmiş olayları yeniden okuyabilirsiniz. Kuyruk ve hata takibi kurulumunu hata izleme ve loglama yazısında anlattık; webhook alıcısı o yazıdaki “sessizlik alarmı”nın en iyi örneğidir, çünkü kesilen bir webhook hata üretmez, yalnızca susar.

Webhook gelmezse ne olur? Tekrar deneme ve geri dolum

Sunucunuz bir saat kapalıysa o saatte olan olaylar kaybolmaz ama ne kadar süreyle yeniden deneneceği sağlayıcıya göre değişir: kimi birkaç saat, kimi üç gün dener, kimi beş başarısız denemeden sonra adresi tamamen kapatır. Bu yüzden iki şey baştan kurulur. Birincisi, sağlayıcının yeniden deneme politikası ve adresin kapanma koşulu teslim dokümanına yazılır. İkincisi, periyodik bir mutabakat işi: gece bir kez sağlayıcıdan son 24 saatin olay ya da işlem listesi çekilir, sizdeki kayıtlarla karşılaştırılır ve eksikler işlenir. Webhook anlık yolu, mutabakat ise emniyet kemeridir; ikisi birlikte kurulmayan entegrasyon bir gün sessizce veri kaybeder.

Kendi sisteminiz webhook gönderecekse

Bir bayi portalı, SaaS ürünü ya da kurumsal panel geliştiriyorsanız bir gün müşterileriniz “sipariş oluşunca bizim sistemimize haber verin” diyecektir. O gün alıcıdan beklediğiniz her şeyi bu kez siz sağlamalısınız: olaylar tekil kimlik ve zaman damgası taşır; her istek müşteriye özel gizli anahtarla imzalanır; gönderim kuyruktan yapılır ve başarısız teslimat artan aralıklarla (1 dk, 5 dk, 30 dk, 2 saat) yeniden denenir; müşterinin panelinde teslimat günlüğü ve “yeniden gönder” düğmesi vardır. En çok atlanan nokta, olayların sürümlenmesidir: gövdeye yeni alan eklemek serbesttir ama var olan bir alanın adını ya da anlamını değiştirmek müşterilerin entegrasyonunu kırar; o yüzden olay şeması sözleşmenin bir parçasıdır. Dışa açık API tasarımı için REST mi GraphQL mi yazısına, genel saldırı yüzeyi için web sitesi güvenliği yazısına bakabilirsiniz.

Webhook projesini bozan beş hata

• İmzayı doğrulamamak ya da doğrulamayı “sonra ekleriz” demek: adres herkese açıktır, ilk günden imzalı çalışır.
• Asıl işi webhook isteğinin içinde yapmak: e-posta sunucusu yavaşlayınca sağlayıcı zaman aşımına düşer, olayı yeniden gönderir ve iş iki kez yapılır.
• Olay kimliğini saklamamak: tekrar gelen olay ayırt edilemez, aynı sipariş iki kez işlenir.
• Test ortamına canlı webhook adresi vermek: sağlayıcının test ve canlı anahtarları ayrıdır, adresleri de ayrı olmalıdır.
• Webhook’u tek gerçek kaynak saymak: mutabakat işi kurulmaz, kesinti olduğunda fark ancak müşteri aradığında anlaşılır.

Sonuç

Webhook, iki sistemi birbirine bağlamanın en hızlı ve en ekonomik yoludur; sorun çıkaran şey webhook değil, alıcı tarafın eksik kurulmasıdır. İmza doğrulama, olay kimliğiyle tekillik, kuyruk ve mutabakat işi: bu dört parça kurulduğunda ödeme, kargo, pazaryeri ya da mesajlaşma entegrasyonunuz yıllarca sessizce çalışır. Entegrasyon katmanı olan bir proje planlıyorsanız özel yazılım hizmetimize göz atabilir ya da doğrudan teklif alabilirsiniz; hangi sağlayıcının webhook sunduğunu, hangisinde polling ve mutabakatla yetinmeniz gerektiğini keşif aşamasında birlikte çıkarırız.