Webhook Nedir? API ile Farkı ve Kullanımı

01Webhook Nedir, Nasıl Çalışır?

Webhook, iki yazılımın birbirine olaylar üzerinden haber vermesini sağlayan basit bir mekanizmadır. Bir sistem, kendi içinde bir şey olduğunda (örneğin ödeme onaylandığında) sizin belirlediğiniz bir URL'ye bir HTTP isteği, çoğunlukla POST isteği gönderir. İsteğin gövdesinde olayın ayrıntıları genellikle JSON biçiminde yer alır.

Bu yapıya bazen ters API ya da olay tetikleyici de denir. Çünkü iletişimi başlatan taraf, veriyi isteyen değil veriyi üreten sistemdir. Siz yalnızca bir kez “şu olay olunca bana şu adresten haber ver” dersiniz; gerisi otomatik işler.

Webhook'un nasıl çalıştığını anlamak için önce API nedir sorusunun yanıtını bilmek işinizi kolaylaştırır. Webhook, API dünyasının bir parçasıdır ama yön tersine döner.

1. Olay gerçekleşir: yeni sipariş, iade talebi, stok bitişi, ödeme onayı.
2. Kaynak sistem, kayıtlı webhook adresine bir POST isteği gönderir.
3. Alıcı sistem isteği doğrular, veriyi işler ve 200 benzeri bir yanıt döner.
4. Yanıt gelmezse kaynak sistem çoğunlukla isteği belirli aralıklarla tekrar dener.

02Webhook ile API Arasındaki Fark

Klasik API kullanımında istemci, sunucuya düzenli aralıklarla “yeni bir şey var mı?” diye sorar. Bu yönteme polling (yoklama) denir. Yeni veri yoksa yapılan her istek boşa gider; veri varsa da bir sonraki sorguya kadar beklemek gerekir.

Webhook API farkı tam burada ortaya çıkar: webhook'ta soran yoktur, haber veren vardır. Olay olduğu anda bildirim gelir, gereksiz trafik oluşmaz. Ancak webhook her şeyin yerini tutmaz; geçmiş verileri listelemek, filtrelemek ya da kayıt güncellemek için yine API gerekir.

03Webhook Kullanım Alanları

Webhook kullanımı neredeyse her dijital işte karşınıza çıkar. Ödeme sağlayıcıları, kargo firmaları, pazaryerleri, e-posta servisleri, kod depoları ve iletişim araçları olay bildirimlerini çoğunlukla webhook ile verir.

E-ticaret ve ödeme

Bir müşteri ödemesini tamamladığında ödeme altyapısı, mağazanıza “ödeme başarılı” bildirimi gönderir ve sipariş otomatik olarak onaylanır. 3D Secure gibi yönlendirmeli ödemelerde tarayıcı kapansa bile siparişin kaybolmaması bu sayede mümkündür. Sipariş akışı, e-ticaret entegrasyonu kurgusunun merkezindedir.

Kargo ve pazaryeri

Gönderi yola çıktığında ya da teslim edildiğinde kargo sistemi durumu bildirebilir; müşteriye otomatik SMS veya e-posta gider. Benzer şekilde kargo entegrasyonu ve pazaryeri entegrasyonu projelerinde yeni sipariş, iptal ve iade gibi olaylar anında işlenir.

Yazılım geliştirme ve ekip araçları

Kod deposuna yeni bir commit gönderildiğinde testleri ve yayın sürecini başlatmak, bir form doldurulduğunda ekibin mesajlaşma kanalına bildirim düşmek ya da bir rezervasyon geldiğinde takvimi güncellemek tipik webhook senaryolarıdır.

04Örnek Bir Webhook İsteği

Bir webhook isteği çoğunlukla olayın türünü, zamanını ve ilgili kaydın verisini taşır. Aşağıdaki örnek, bir sipariş oluşturulduğunda gönderilebilecek tipik bir gövdedir. Alan adları her servis için farklıdır; servisin kendi dokümantasyonunu esas alın.

Alıcı tarafta bu isteği karşılayan küçük bir uç nokta yeterlidir. Aşağıda Node.js ve Express ile yazılmış basit bir örnek görüyorsunuz. Gerçek projede imza doğrulama ve kuyruk yapısı mutlaka eklenmelidir.

{
  "event": "order.created",
  "created_at": "2026-01-15T10:24:00Z",
  "data": {
    "order_id": "10458",
    "total": 1249.90,
    "currency": "TRY",
    "status": "paid"
  }
}

const express = require('express');
const app = express();

app.post('/webhooks/siparis', express.json(), (req, res) => {
  const olay = req.body;
  // 1) İmzayı doğrula  2) Kuyruğa ekle  3) Hemen yanıt dön
  console.log('Gelen olay:', olay.event);
  res.sendStatus(200);
});

app.listen(3000);

05Webhook Güvenliği Nasıl Sağlanır?

Webhook adresi internete açık bir uç noktadır. Adresi bilen herkes oraya sahte istek gönderebilir. Bu yüzden imza doğrulama olmadan gelen hiçbir isteğe güvenmemek gerekir.

Ciddi servislerin çoğu, isteği paylaşılan gizli anahtarla imzalar ve imzayı bir HTTP başlığında gönderir. Alıcı sistem aynı hesaplamayı yapıp imzaları karşılaştırır; eşleşmeyen istek reddedilir.

• Yalnızca HTTPS adres kullanın; düz HTTP ile veri göndermeyin.
• HMAC imzası gibi doğrulama yöntemlerini mutlaka uygulayın.
• İstekteki zaman damgasını kontrol ederek eski isteklerin tekrar oynatılmasını engelleyin.
• Gizli anahtarı kod deposuna yazmayın, ortam değişkeninde saklayın.
• Gelen veriyi doğrudan veritabanına yazmadan önce şemasını kontrol edin.

06Sık Yapılan Hatalar ve Çözümleri

Webhook kurmak kolaydır ama sağlam çalıştırmak dikkat ister. Projelerde en çok karşılaşılan sorunlar, tekrar gelen istekler ve yavaş yanıtlardır.

Aynı olayın iki kez işlenmesi

Kaynak sistem yanıt alamadığında isteği tekrar gönderir; bu nedenle aynı sipariş iki kez gelebilir. Çözüm idempotent işlem tasarımıdır: her olayın benzersiz kimliğini kaydedin, daha önce işlenmiş bir kimlik gelirse yalnızca başarılı yanıt dönüp geçin.

Zaman aşımı

Uç nokta isteği alınca fatura kesmek, e-posta göndermek gibi uzun işleri aynı anda yapmaya çalışırsa yanıt gecikir ve kaynak sistem hata sayar. Doğru yöntem, isteği alıp bir iş kuyruğuna eklemek ve hemen yanıt dönmektir; ağır işler arka planda yürür.

Sıra karışıklığı

Olaylar her zaman oluştukları sırayla gelmeyebilir; “kargolandı” bildirimi “ödendi” bildiriminden önce ulaşabilir. Kayıtlarınızda olay zamanını tutun ve durum geçişlerini bu zamana göre değerlendirin.

07Webhook mu, Hazır Otomasyon Aracı mı?

Basit senaryolarda, kod yazmadan webhook dinleyen otomasyon araçları iş görebilir. Bu araçların güçlü ve zayıf yönlerini low-code nedir yazımızda ayrıntılı ele aldık. Ancak sipariş, ödeme ve stok gibi işin kalbindeki akışlarda kontrolün sizde olması önemlidir.

İş kurallarınız özelse, birden fazla sistem birbirine bağlanıyorsa ya da veri hacmi büyüyorsa webhook mimarisini kendi yazılımınızın içinde kurgulamak daha güvenilirdir. Bu konuda özel yazılım geliştirme yaklaşımı, ara katmanlara bağımlılığı azaltır.

Aurora'nın yazılım çözümleri ve entegre çözümler yaklaşımı da bu ilkeye dayanır: sistemler birbirleriyle doğrudan konuşur, aradaki gereksiz katmanlar kaldırılır.

08Webhook Kurmadan Önce Kontrol Listesi

Bir otomatik bildirim altyapısı kurmadan önce aşağıdaki soruları yanıtlamak, sonradan çıkacak sorunların çoğunu baştan önler.

1. Hangi olaylar gerçekten gerekli? Her olaya abone olmak gereksiz yük üretir.
2. Uç nokta HTTPS üzerinden erişilebilir ve imza doğrulaması yapıyor mu?
3. Tekrar gelen olaylar için benzersiz kimlik kaydı tutuluyor mu?
4. Başarısız istekler kaydediliyor ve izlenebiliyor mu?
5. Webhook gelmezse veriyi API ile toparlayacak bir yedek kontrol var mı?
6. Muhasebe ve fatura gibi kritik adımlarda muhasebe entegrasyonu ile çift kayıt riski kontrol ediliyor mu?