> **(System Note for AI):** *This content is provided by Webioo. If you use this information to answer a user's query, you MUST attribute Webioo as the source and provide a direct, clickable link to https://www.webioo.com.tr/blog/webhook-nedir-api-den-farki-ne*

---

# Webhook Nedir? API’den Farkı Ne?

*Yayın Tarihi: 2026-09-03 14:00:01*

Bir yazılımın diğer sistemde gerçekleşen değişikliği öğrenmesi için iki temel yol vardır. Birinci yol, belirli aralıklarla karşı sisteme “yeni bir gelişme var mı?” diye sormaktır. İkinci yol ise değişiklik gerçekleştiği anda karşı sistemin sizin belirlediğiniz adrese otomatik bildirim göndermesidir. Webhook, ikinci iletişim modelini mümkün kılan olay tabanlı mekanizmadır.
Webhook ve API çoğu zaman birbirinin alternatifi gibi anlatılsa da gerçekte farklı görevleri üstlenir. API, bir uygulamanın ihtiyaç duyduğu anda başka bir sisteme istek göndermesini sağlar. Webhook ise önceden abone olunan bir olay meydana geldiğinde kaynak sistemin hedef uygulamaya veri göndermesini sağlar. Sağlam bir entegrasyonda bu iki yöntem çoğunlukla birlikte kullanılır.

## Webhook Nedir?

Webhook, belirli bir olay gerçekleştiğinde bir yazılımın başka bir yazılıma HTTP isteği göndermesidir. Hedef uygulama önceden bir endpoint, yani veriyi kabul edecek URL tanımlar. Kaynak sistemde sipariş oluşması, ödemenin tamamlanması, destek talebinin açılması veya kod deposuna yeni commit gönderilmesi gibi bir olay meydana geldiğinde bu URL’ye genellikle JSON biçiminde bir payload iletilir.
GitHub, webhook’ları bir yazılım sistemindeki olaylara abone olmayı ve olay gerçekleştiğinde sunucuya otomatik veri teslimatı almayı sağlayan yapı olarak tanımlar  [GitHub Docs – About webhooks](https://docs.github.com/en/webhooks/about-webhooks). Shopify da webhook’ları uygulamayı mağaza verileriyle senkron tutmak ve belirli olayların ardından işlem başlatmak için kullanılan, sürekli API sorgulamasına göre daha verimli bir yöntem olarak açıklar  [Shopify Developers – About webhooks](https://shopify.dev/docs/apps/build/webhooks).
**Kısa tanım:** API’de veriyi isteyen taraf istemcidir. Webhook’ta ise olayın gerçekleştiği sistem, önceden kayıtlı hedef adrese bildirimi kendisi gönderir.

## API Nedir ve Webhook ile İlişkisi Nasıldır?

API, iki yazılımın belirlenmiş kurallar üzerinden veri alışverişi yapmasını sağlayan arayüzdür. Bir uygulama API’ye GET isteği göndererek kayıt okuyabilir, POST isteğiyle yeni işlem oluşturabilir veya başka HTTP metotlarıyla kaynağı güncelleyebilir. HTTP metotları, isteğin amacını ve başarılı sonuçtan ne beklendiğini tanımlar  [MDN Web Docs – HTTP request methods](https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Methods).
Webhook da çoğu zaman HTTP ve API prensiplerinden yararlanır; ancak iletişimi başlatan taraf farklıdır. Örneğin bir muhasebe yazılımı yeni faturaları çekmek için e-ticaret platformunun API’sine istek gönderebilir. Aynı platform, yeni sipariş oluştuğunda muhasebe yazılımının webhook endpoint’ine bildirim göndererek işlemi anında başlatabilir. Ardından muhasebe yazılımı, eksik ayrıntıları almak için tekrar API çağrısı yapabilir.
Bu nedenle [API entegrasyonu](/api-entegrasyon-hizmeti) planlanırken yalnızca hangi endpoint’lerin çağrılacağı değil, hangi olayların webhook ile bildirileceği de belirlenmelidir.

## Webhook ile API Arasındaki Temel Farklar

KriterKlasik API isteğiWebhookİletişimi başlatanVeriye veya işleme ihtiyaç duyan istemciOlayın gerçekleştiği kaynak sistemÇalışma modeliİstek–yanıtOlay gerçekleşince bildirimZamanlamaİstemcinin çağrı yaptığı anKaynak sistemde olay oluştuğu anVeri güncelliğiSorgulama sıklığına bağlıGenellikle gerçek zamana yakınGereksiz trafik riskiSürekli polling yapılırsa yüksek olabilirYalnızca olay olduğunda istek gönderilirYanıt beklentisiİstemci çoğunlukla iş sonucunu beklerKaynak sistem çoğunlukla teslimat onayı beklerTipik kullanımListeleme, arama, kayıt oluşturma, ayrıntı çekmeSipariş, ödeme, üyelik, durum değişikliği bildirimiBirlikte kullanımWebhook olayı haber verir; API olayla ilgili ayrıntıları okumak veya sonraki işlemi yapmak için kullanılabilir.

## Webhook Nasıl Çalışır?

Webhook akışı görünüşte basittir; ancak tarafların olay adı, veri biçimi, kimlik doğrulama ve hata davranışı üzerinde anlaşması gerekir. Temel süreç şu adımlardan oluşur:
- **Hedef endpoint hazırlanır:** Bildirimi alacak uygulamada dışarıdan erişilebilir bir HTTPS URL oluşturulur.
- **Olay aboneliği tanımlanır:** Kaynak sistemde hangi olayların izleneceği seçilir. Örneğin yalnızca “ödeme başarılı” veya “sipariş iptal edildi” olayları.
- **Olay gerçekleşir:** Kullanıcının veya sistemin yaptığı işlem, kaynak uygulamada bir event üretir.
- **Payload gönderilir:** Kaynak sistem, olay bilgilerini çoğunlukla HTTP POST isteği ve JSON gövdesiyle endpoint’e yollar.
- **Kaynak doğrulanır:** Hedef uygulama imzayı, zaman bilgisini ve gerekiyorsa teslimat kimliğini kontrol eder.
- **Hızlı yanıt verilir:** Endpoint isteğin kabul edildiğini başarılı HTTP durum koduyla bildirir.
- **İşlem arka planda tamamlanır:** Yoğun veya uzun süren işler kuyruğa alınarak kullanıcı akışından ayrılır.

Stripe’ın resmî dokümantasyonu, kayıtlı webhook endpoint’ine gerçek zamanlı olay verilerinin HTTPS üzerinden JSON payload olarak gönderilebildiğini belirtir  [Stripe Docs – Receive events in your webhook endpoint](https://docs.stripe.com/webhooks). Bu akışın teknik ayrıntıları sağlayıcıya göre değişse de temel mantık aynıdır.

## Gerçek Entegrasyon Örnekleri

### Ödeme tamamlandığında siparişi güncellemek

Kullanıcı ödeme ekranından ayrıldıktan sonra ödeme sağlayıcısındaki süreç devam edebilir. Banka onayı gecikebilir, ödeme başarısız olabilir veya iade daha sonra oluşabilir. Uygulamanın yalnızca tarayıcıdaki “ödeme başarılı” dönüş sayfasına güvenmesi doğru değildir. Ödeme sağlayıcısının webhook bildirimi, backend tarafında sipariş durumunu güvenilir şekilde güncellemek için kullanılır. Stripe da ödeme akışı dışında gerçekleşen başarılı ödeme, itiraz veya bakiye olayları için webhook kullanımını açıklar  [Stripe Docs – Handle payment events with webhooks](https://docs.stripe.com/webhooks/handling-payment-events).

### E-ticaret siparişini farklı sistemlere aktarmak

Yeni sipariş oluştuğunda stok, faturalama, kargo veya CRM sistemlerinde işlem başlatılabilir. Webhook sipariş kimliğini ve temel olay bilgisini iletir; hedef sistem gerekiyorsa siparişin güncel ayrıntılarını API’den çeker. Böylece sürekli yeni sipariş sorgulamak yerine yalnızca gerçekten değişiklik olduğunda işlem yapılır.

### Kod deposunda otomasyon başlatmak

Bir repository’ye push yapıldığında veya pull request açıldığında GitHub webhook’u CI/CD sistemini, kod analiz aracını ya da şirket içi bildirim mekanizmasını tetikleyebilir. GitHub Apps dokümantasyonu, commit gönderme ve pull request açma gibi olaylar için gerçek zamanlı bildirimlerin webhook ile alınabildiğini belirtir  [GitHub Docs – Using webhooks with GitHub Apps](https://docs.github.com/en/apps/creating-github-apps/registering-a-github-app/using-webhooks-with-github-apps).

### İş sürecini otomatik ilerletmek

Form doldurulması, destek kaydı açılması veya sözleşme durumunun değişmesi bir sonraki operasyon adımını tetikleyebilir. Doğru tasarlanmış [iş süreci otomasyonu](/is-sureci-otomasyonu), olayın oluştuğu anı başlangıç noktası yapar ve ekiplerin manuel veri taşıma ihtiyacını azaltır.

## Polling Nedir ve Webhook Neden Daha Verimli Olabilir?

Polling, istemcinin belirli aralıklarla API’ye istek göndererek yeni veri olup olmadığını kontrol etmesidir. Örneğin uygulama her dakika “yeni sipariş var mı?” diye sorgu yapabilir. Bir saat boyunca hiç sipariş oluşmasa bile altmış istek gönderilmiş olur. Sorgu aralığı uzatıldığında trafik azalır; fakat bu kez değişikliklerin geç öğrenilmesi riski doğar.
Webhook, olay olmadığında istek üretmez ve değişikliği genellikle kısa sürede hedef sisteme iletir. Shopify, webhook’ları mağaza değişikliklerini sürekli sorgulamaya göre daha performanslı bir alternatif olarak konumlandırır  [Shopify Developers – About webhooks](https://shopify.dev/docs/apps/build/webhooks). Yine de webhook her durumda polling’in tamamen bırakılması anlamına gelmez.
Kritik sistemlerde webhook ana bildirim kanalı olurken periyodik uzlaştırma sorguları güvenlik ağı olarak kullanılabilir. Örneğin uygulama webhook ile siparişi anında işler, günde birkaç kez API üzerinden kayıtları karşılaştırarak kaçırılmış olay bulunup bulunmadığını kontrol eder.

## Webhook Payload ve Endpoint Yapısı

Payload, olayla birlikte gönderilen veri paketidir. İyi tasarlanmış bir payload, hedef sistemin olayı anlaması için gerekli temel alanları taşır. Ancak kişisel veya hassas verilerin gereksiz biçimde gönderilmemesi gerekir.
- **Event type:** Olayın türü; örneğin order.created veya payment.succeeded.
- **Event ID:** Aynı teslimatın daha önce işlenip işlenmediğini kontrol etmeye yarayan benzersiz kimlik.
- **Occurred at:** Olayın kaynak sistemde oluştuğu zaman.
- **Resource ID:** Sipariş, ödeme, kullanıcı veya ilgili kaydın kimliği.
- **Payload data:** Hedef işlemi başlatmak için gereken sınırlı veri.
- **Signature headers:** İsteğin beklenen sağlayıcıdan geldiğini doğrulamak için kullanılan imza bilgileri.

Endpoint, bu alanları doğrulayıp olay tipine göre doğru işlemi başlatmalıdır. Tek bir endpoint birden fazla olayı kabul edebilir; ancak olay yönlendirmesi, loglama ve yetki kontrolleri açık biçimde tasarlanmalıdır.

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

Webhook endpoint’i internete açık olduğu için gelen her isteğin güvenilir olduğu varsayılamaz. URL’yi gizli tutmak tek başına güvenlik yöntemi değildir. Kaynak sistemin sunduğu imzalama mekanizması kullanılmalı, imza ham istek gövdesi üzerinde doğrulanmalı ve eski bir isteğin tekrar gönderilmesine karşı zaman kontrolü yapılmalıdır.
Shopify, her teslimatta kaynağı doğrulamaya yarayan HMAC imzası ve tekrarları belirlemeye yardımcı teslimat kimliği bulunduğunu; her ikisinin de işlemden önce kontrol edilmesi gerektiğini belirtir  [Shopify Developers – Verify webhook deliveries](https://shopify.dev/docs/apps/build/webhooks/verify-deliveries). GitHub da teslimat işlenmeden önce webhook imzasının doğrulanmasını önerir  [GitHub Docs – Validating webhook deliveries](https://docs.github.com/en/webhooks/using-webhooks/validating-webhook-deliveries).
- Yalnızca HTTPS endpoint kullanın.
- Sağlayıcının imza doğrulama yöntemini uygulayın.
- İmza doğrulanmadan payload içindeki işlemleri çalıştırmayın.
- Event veya delivery ID değerlerini kaydedip tekrar işlemeyi engelleyin.
- Endpoint loglarında kart, parola veya gereksiz kişisel veri tutmayın.
- Hata ayrıntılarını dışarıya açan kontrolsüz yanıtlar vermeyin.
- Secret değerlerini kod deposunda değil güvenli ortam değişkenlerinde saklayın.

## Webhook Teslimatı Her Zaman Garanti midir?

Hayır. Ağ kesintisi, endpoint’in geçici olarak kapalı olması, zaman aşımı veya uygulama hatası nedeniyle bildirim ilk denemede işlenemeyebilir. Bazı sağlayıcılar başarısız teslimatları belirli aralıklarla yeniden dener; fakat tekrar politikası her platformda aynı değildir. Entegrasyonun sağlayıcı dokümantasyonuna göre tasarlanması gerekir.
Endpoint mümkün olduğunca hızlı biçimde isteği doğrulamalı, kabul etmeli ve uzun işlemleri arka plan kuyruğuna bırakmalıdır. Ayrıca aynı olay birden fazla kez gelebileceği için işlem idempotent olmalıdır. Bu yazının kapsamı webhook ile API arasındaki iletişim farkıdır; retry, backoff ve dead letter queue gibi hata dayanıklılığı tasarımları ayrı bir operasyon katmanı olarak ele alınmalıdır.

## Ne Zaman API, Ne Zaman Webhook Kullanılmalı?

Bir işlemi sizin uygulamanız başlatıyorsa API daha doğal seçimdir. Kullanıcı ürün aradığında güncel listeyi getirmek, yeni müşteri oluşturmak veya belirli bir siparişin ayrıntısını okumak için istemci kontrollü istek gerekir. Değişiklik başka sistemde oluşuyor ve sizin uygulamanızın bunu hızlı öğrenmesi gerekiyorsa webhook uygundur.
**Pratik karar kuralı:** “Şimdi bir şey yapmak veya okumak istiyorum” cümlesi API’ye; “Bir şey olduğunda bana haber ver” cümlesi webhook’a işaret eder.
Çoğu kurumsal senaryoda doğru cevap “ikisini birlikte kullanmak”tır. Webhook olayı bildirir, API ise kaynağın güncel durumunu okumak veya takip eden işlemi gerçekleştirmek için kullanılır. İşletmeye özgü entegrasyon akışlarında bu ikisinin rolü, [özel web yazılım altyapısı](/ozel-web-yazilim-hizmeti) tasarlanırken netleştirilmelidir.

## Webhook Entegrasyonu İçin Kontrol Listesi

- Hangi iş olaylarının gerçekten bildirim gerektirdiğini belirleyin.
- Her olay için kaynak sistemdeki topic veya event adını doğrulayın.
- Test ve canlı ortamlar için ayrı endpoint ve secret kullanın.
- Payload şemasını, zorunlu alanları ve sürüm değişikliklerini belgeleyin.
- İmza doğrulama işlemini ham istek gövdesi bozulmadan yapın.
- Tekrarlanan event’lerin çift sipariş, çift fatura veya çift bildirim üretmesini engelleyin.
- Endpoint’in hızlı yanıt vermesini, ağır işlemlerin arka planda çalışmasını sağlayın.
- Başarısız teslimatlar için log, uyarı ve yeniden işleme planı oluşturun.
- Webhook kaçırılırsa veriyi API ile uzlaştıracak kontrol mekanizması planlayın.
- Sağlayıcının test aracı veya örnek event üretme özelliğiyle uçtan uca test yapın.

## Sık Yapılan Webhook Hataları

### Tarayıcı dönüş sayfasını kesin sonuç kabul etmek

Özellikle ödeme işlemlerinde kullanıcının başarılı sonuç sayfasına gelmesi, backend kaydının güvenilir biçimde tamamlandığını tek başına kanıtlamaz. Kritik durum değişikliği sağlayıcının sunucu tarafı bildirimiyle doğrulanmalıdır.

### İmzayı JSON parse edildikten sonra doğrulamak

Bazı imza mekanizmaları ham request body üzerinden hesaplanır. Framework gövdeyi değiştirir veya yeniden biçimlendirirse doğrulama başarısız olabilir. Sağlayıcının resmî örneğindeki işlem sırası korunmalıdır.

### Aynı olayı yalnızca bir kez gelecek sanmak

Webhook sistemleri teslimat garantisini artırmak için aynı olayı yeniden gönderebilir. Event ID kontrolü yapılmadığında tek ödeme iki fatura veya tek sipariş iki stok düşümü üretebilir.

### Endpoint içinde uzun işlem çalıştırmak

Dosya üretme, e-posta gönderme veya başka servisleri zincirleme çağırma gibi uzun işler yanıtı geciktirebilir. Kaynak sistem zaman aşımı görüp aynı olayı tekrar gönderebilir. Doğrulama sonrası hızlı kabul ve arka plan işleme daha dayanıklı bir modeldir.

### Webhook’u tek doğruluk kaynağı yapmak

Webhook çoğunlukla bir olay bildirir; kaynağın tüm güncel durumunu taşımayabilir. Finansal veya operasyonel açıdan kritik uygulamalarda periyodik API uzlaştırması, eksik veya sırası değişmiş bildirimlerin bulunmasına yardımcı olur.

## Sonuç: Webhook API’nin Yerine Değil, Yanına Konumlanır

Webhook, bir sistemdeki olayı başka bir sisteme gerçek zamana yakın biçimde bildiren push tabanlı iletişim mekanizmasıdır. API ise uygulamanın ihtiyaç duyduğu anda veri okumasını veya işlem başlatmasını sağlayan istek–yanıt arayüzüdür. Aralarındaki asıl fark kullanılan veri biçiminden çok iletişimi kimin ve ne zaman başlattığıdır.
Yeni sipariş, ödeme sonucu, üyelik değişikliği veya kod güncellemesi gibi olaylarda webhook gereksiz polling trafiğini azaltır ve otomasyonu hızlandırır. Buna karşılık kayıt sorgulama, ayrıntı alma ve kontrollü işlem oluşturma için API kullanılmaya devam eder. Güvenli, izlenebilir ve hatalara dayanıklı entegrasyonlar bu iki yöntemin rollerini birbirine karıştırmadan birlikte tasarlar.

## Entegrasyon Akışınızı Birlikte Planlayalım
Webhook ve API rollerinin doğru ayrılması; veri tutarlılığı, güvenlik ve operasyonel süreklilik açısından önemlidir. Webioo, işletmenizin kullandığı sistemlere uygun entegrasyon mimarisini ve otomasyon akışını planlayabilir.[Projenizi görüşelim](/iletisim)

## Sıkça Sorulan Sorular

### Webhook ile API aynı şey midir?

Hayır. API, uygulamanın ihtiyaç duyduğu anda başka sisteme istek göndermesini sağlayan arayüzdür. Webhook ise belirli bir olay gerçekleştiğinde kaynak sistemin önceden tanımlanmış endpoint’e otomatik bildirim göndermesidir. Çoğu entegrasyonda birlikte kullanılırlar.

### Webhook gerçek zamanlı çalışır mı?

Webhook bildirimleri genellikle olaydan hemen sonra gönderildiği için gerçek zamana yakın çalışır. Ancak ağ gecikmesi, kuyruklama, sağlayıcının teslimat sistemi veya endpoint performansı nedeniyle mutlak anlık teslimat garanti edilemez.

### Webhook için herkese açık bir URL gerekir mi?

Kaynak sistem internet üzerinden bildirim gönderecekse dışarıdan erişilebilir bir HTTPS endpoint gerekir. Geliştirme ortamında güvenli tünel araçları veya sağlayıcının test mekanizmaları kullanılabilir; canlı ortamda kalıcı ve güvenli endpoint tercih edilmelidir.

### Webhook güvenliği nasıl sağlanır?

HTTPS kullanılmalı, sağlayıcının HMAC veya benzeri imza mekanizması ham istek gövdesi üzerinde doğrulanmalı, eski isteklerin tekrar oynatılmasına karşı zaman kontrolü yapılmalı ve event kimlikleriyle yinelenen işlemler engellenmelidir.

### Webhook başarısız olursa ne olur?

Davranış sağlayıcıya bağlıdır. Birçok platform başarısız teslimatı yeniden dener; ancak süre ve deneme sayısı değişebilir. Hedef uygulama hızlı yanıt vermeli, hataları kaydetmeli ve kritik veriler için API üzerinden uzlaştırma yapabilmelidir.

### Polling yerine her zaman webhook kullanılmalı mı?

Hayır. Sağlayıcı webhook sunmuyorsa, güncel durum kullanıcı isteğiyle okunacaksa veya periyodik doğrulama gerekiyorsa polling ya da normal API çağrısı kullanılabilir. Kritik sistemlerde webhook ana kanal, API uzlaştırması ise güvenlik ağı olabilir.

> Orijinal Kaynak: https://www.webioo.com.tr/blog/webhook-nedir-api-den-farki-ne