Kitap 03 · Backend ve API'lerSayfa 47 / 48

Webhook

Türkçe karşılığı: web kancası
Okunuşu: vebhuk

Günlük kullanımda çoğunlukla İngilizcesi tercih edilir.

Güncellendi 29 Eylül 20262 dk okuma

Kısaca

Webhook, bir uygulamanın, tamamlanan bir ödeme gibi belirli bir olay gerçekleştiği anda sizin verdiğiniz bir URL'ye otomatik olarak gönderdiği HTTP isteğidir.

Webhook nedir?

Webhook, bir sistemin bir şey olduğu anda başka bir sistemi haberdar etmesini sağlar. Bir servise URL kaydedersiniz; yeni bir sipariş, başarısız bir ödeme ya da bir kod deposuna yapılan push gibi seçtiğiniz bir olay gerçekleştiğinde servis, olayın ayrıntılarını genellikle JSON biçiminde taşıyan bir HTTP POST isteğini bu URL'ye gönderir.

Webhook'lar polling'in tersidir. Polling'de uygulamanız bir API'ye bir şeyin değişip değişmediğini tekrar tekrar sorar; bu da istekleri boşa harcar ve gecikme ekler. Webhook'ta ise diğer servis bilgiyi yalnızca yeni bir şey olduğunda size iletir; bu yüzden webhook'lara bazen ters API (reverse API) denir.

Gündelik bir benzetme, kargo takip sayfasını birkaç dakikada bir yenilemekle, kargo geldiğinde kısa mesaj almak arasındaki farktır. Webhook'lar; ödeme sağlayıcıları, sohbet araçları, Git barındırma servisleri ve CI/CD hatları tarafından otomatik işleri tetiklemek için yaygın olarak kullanılır.

Webhook URL'si herkese açık olduğundan alıcı her isteği doğrulamalıdır; bu genellikle paylaşılan bir gizli anahtarla hesaplanan bir imzanın kontrol edilmesiyle yapılır. Alıcılar ayrıca 2xx durum koduyla hızlıca yanıt vermeli ve tekrarlanan teslimatları güvenle işlemelidir, çünkü çoğu gönderici teslimat başarısız olduğunda yeniden dener.

Bir bakışta

Birkaç saniyede bir “ödendi mi?” diye sormak yerine uygulamanız diğer servise bir URL verir ve bir şey olduğu anda haber alır.

Önemli noktalar

Webhook, bir olayın tetiklediği HTTP isteğidir.
Gönderen veriyi size iletir, dolayısıyla polling yapmanız gerekmez.
URL'yi siz verirsiniz; diğer servis onu çağırır.
İmzaları doğrulayın, çünkü herkese açık bir URL'ye herkes istek gönderebilir.
Yeniden denemeleri bekleyin ve işleyicinizi birden fazla kez çalışmaya karşı güvenli hale getirin.

Örnek

Express.js'te bir webhook almakjavascript

// Receive webhook events from a payment provider
app.post("/webhooks/payments", express.json(), (req, res) => {
  // In production, verify the request's signature header first
  const event = req.body;

  if (event.type === "payment.succeeded") {
    markOrderAsPaid(event.data.orderId);
  }

  // Reply quickly with 200 so the sender does not retry
  res.sendStatus(200);
});

Sık sorulan sorular

Webhook ile API arasındaki fark nedir?

Normal bir API çağrısında uygulamanız veriyi istediği zaman talep eder. Webhook'ta ise diğer uygulama bir olay gerçekleştiğinde veriyi size otomatik olarak gönderir; bu yüzden webhook'lar sıklıkla olay güdümlü (event-driven) ya da ters API olarak tanımlanır.

Webhook ile polling arasındaki fark nedir?

Polling, hiçbir şey değişmemiş olsa bile sunucudan belirli aralıklarla güncelleme istemek demektir. Webhook ise güncellemeyi tam olay gerçekleştiği anda bir kez iletir; bu hem daha hızlıdır hem de çok daha az istek kullanır.

Bir webhook'un güvenliği nasıl sağlanır?

HTTPS kullanın, göndericinin istek başlıklarına eklediği imzayı paylaşılan bir gizli anahtarla doğrulayın ve kontrolü geçemeyen ya da çok eski olan istekleri reddedin.

İlgili sayfalar

Bu sayfada bir hata ya da eksik mi gördünüz?Düzeltme önerin