API ve webhook nedir, farkı ne

İki sistemi birbirine bağlamadan önce: sormakla haber almanın farkı, siparişin mağazadan muhasebeye yolu ve satın almadan önce dokümantasyonda nelere bakılacağı.

· 11 dk okumaYapay zeka

Kısa cevap

API, bir programın yazılımla kullanılabilen kapısıdır: siz sorarsınız, karşı sistem cevap verir. Webhook bunun tersidir: karşı sistem bir şey olunca önceden verdiğiniz adrese kendiliğinden haber gönderir. Satın almadan önce dokümantasyonda API, kimlik doğrulama, hız sınırı ve webhook olup olmadığına bakın.

Şöyle düşünün: bir mağazanın siparişleri bir panelde toplanıyor, faturalar ise ayrı bir muhasebe programında kesiliyor. Her akşam biri panelden yeni siparişlere bakıp bunları muhasebe programına yeniden yazıyor. İki programı birbirine bağlamak bu işi ortadan kaldırabilir. Bağlanıp bağlanamayacaklarını da iki kelime belirler: API ve webhook. Bu yazı API ve webhook nedir ve farkı ne sorusunu, bir bağlantıya yatırım yapıp yapmayacağına karar veren iş sahibinin gözünden ele alıyor. Önce iki kavramı sade dille anlatıyor, sonra satın almadan önce dokümantasyonda nelere bakacağınızı ve satıcıya ne soracağınızı sıralıyor.

Hangi işi otomatikleştireceğinizi henüz seçmediyseniz önce otomasyona nereden başlamalı yazısındaki envantere bakın. Burada araç seçmiyoruz; bağlantının nasıl kurulduğunu ve nerede koptuğunu anlatıyoruz.

API nedir

MDN sözlüğü API’yi, bir yazılımın içinde bulunan ve ona insan arayüzü yerine yazılım aracılığıyla erişmeyi sağlayan özellikler ve kurallar bütünü olarak tanımlar. Aynı sayfa API’yi, onu sunan uygulama ile üçüncü taraf yazılım arasında bir sözleşmeye benzetir.

İş diliyle: API, bir programın dışarıya açtığı, kuralları yazılı kapıdır. Ekranda butona basan siz değil, başka bir program olur. “Son kontrolden bu yana oluşan siparişleri ver” ya da “bu faturayı kaydet” gibi bir istek gönderir, karşı sistem de bir cevap döner. Önemli olan yön: API’de konuşmayı başlatan, bağlanmak isteyen taraftır.

Webhook nedir

Webhook’ta yön tersine döner. Karşı sistemde bir adres tanımlarsınız; orada bir olay olunca karşı sistem o adrese, olayın bilgisini taşıyan bir mesaj gönderir. Stripe’ın dokümanına göre, bir webhook uç noktası (mesajın gideceği adres) kaydettiğinizde, olaylar olunca Stripe verileri bu adrese kendisi gönderir; bunu HTTPS üzerinden, JSON adlı düz metin biçiminde yapar. Shopify ise webhook’ları, mağazadaki belirli olaylar hakkında neredeyse gerçek zamanlı veri almanın yolu olarak anlatır ve “değişiklik var mı” diye sürekli sormaya göre verimli bir seçenek olarak sunar. Terimin kısa tanımı için sözlükteki webhook maddesine de bakabilirsiniz.

Özetle API’de “ben soruyorum”, webhook’ta “bir şey olunca bana haber ver” demiş olursunuz.

Aynı sipariş, iki yol

Mağazadan muhasebeye giden bir siparişi iki biçimde taşıyabilirsiniz.

API ile. Muhasebe tarafındaki program ya da aradaki otomasyon aracı, belli aralıklarla mağazanın API’sine “yeni sipariş var mı” diye sorar ve gelen listedeki her siparişi muhasebeye yazar. Haberin ne kadar geç geleceğini sorma sıklığınız belirler; soruların birçoğu “yok” cevabıyla döner.

Webhook ile. Mağazada “sipariş oluştu” olayına bir abonelik tanımlarsınız ve mesajın gideceği adresi verirsiniz. Sipariş geldiği an mağaza o adrese bir mesaj gönderir. Aşağıdaki, böyle bir mesajın (payload) sadeleştirilmiş bir örneğidir; bütün değerler uydurmadır.

{
  "event": "order.created",
  "order_no": "EXAMPLE-0001",
  "customer": "Example Customer",
  "items": [{ "sku": "EXAMPLE-SKU", "quantity": 1 }]
}

Gerçek bir mesaj çok daha fazla alan taşır; hangi alanların geldiği ürünün dokümantasyonunda yazar. Alıcı taraf mesajı okur ve siparişi muhasebe programına yazar.

Aynı sipariş iki yolla: API ile muhasebe programı sorar, webhook ile mağaza haber verir API: siz sorarsınız Muhasebe programı sorar: yeni sipariş var mı? Mağaza yanıt verir: yeni siparişlerin listesi gelir Sipariş muhasebe programına yazılır Webhook: size haber verilir Mağazada sipariş oluşur Mağaza, önceden verilen adrese bildirim gönderir Muhasebe tarafı bildirimi alır ve siparişi yazar Aynı sipariş iki yolla: API ile muhasebe programı sorar, webhook ile mağaza haber verir API: siz sorarsınız Muhasebe programı sorar: yeni sipariş var mı? Mağaza yanıt verir: yeni siparişlerin listesi gelir Sipariş muhasebe programına yazılır Webhook: size haber verilir Mağazada sipariş oluşur Mağaza, önceden verilen adrese bildirim gönderir Muhasebe tarafı bildirimi alır ve siparişi yazar
Şekil: Aynı sipariş muhasebeye iki yoldan ulaşır; mavi kutu, yolu başlatan tarafı gösterir.

İkisini yan yana koyunca fark daha net görünür.

Soru API Webhook
Kim başlatır? Siz ya da aracınız Karşı sistem
Ne zaman çalışır? Sorduğunuz anda Olay olduğunda
En çok neye yarar? Kayıt okumak, oluşturmak, güncellemek; geçmiş veriyi çekmek Bir olay olur olmaz bir işi başlatmak
Kaçırılırsa? Bir sonraki soruda yakalanır Mesaj ulaşmazsa yeniden denenebilir, ama teslimat her üründe garanti edilmez

Çoğu gerçek bağlantı ikisini birlikte kullanır: webhook “bir şey oldu” der, API ise gerektiğinde ayrıntıyı ve eksik kalanı çeker. Shopify’ın dokümanı da webhook’a tek başına güvenmemenizi, belirli aralıklarla API’den veri çekip iki tarafın kayıtlarını eşitleyen bir kontrol işi (uzlaştırma) çalıştırmanızı öneriyor.

Bu çağrıları sıfırdan yazmanız gerekmez: n8n, Make ve Zapier gibi akış araçları API’ye bağlanmak ve webhook almak için hazır parçalar sunar. Üçünün farkını n8n, Make ve Zapier farkı yazısında anlattık; araç hangisi olursa olsun, bağlanacağınız ürünün API’si ya da webhook’u yoksa bu hazır parçaların bağlanacak yeri çoğu zaman olmaz.

Satın almadan önce dokümantasyonda neye bakılır

Bir yazılımı ya da bir hizmeti seçmeden önce ürünün geliştirici dokümantasyonunu açın; genellikle “API”, “Developers” ya da “Entegrasyonlar” başlığı altındadır. Teknik biri olmanız gerekmez, beş şeyi arayın.

  1. API var mı ve neleri kapsıyor? Arayüzde yaptığınız her şey API’den yapılamayabilir. Sizin sürecinizin ihtiyaç duyduğu işlem (siparişleri okumak, fatura oluşturmak) listede yazıyor mu? Eski programlarda API hiç olmayabilir; bu durumda düzenli dosya aktarımı gibi başka yollar bazen çıkar, her zaman çıkmaz.
  2. Kimlik doğrulama nasıl yapılıyor? Yani karşı sistem, isteği gönderenin siz olduğunu nasıl anlıyor? Örneğin Stripe’ın dokümanı, Stripe’ta API anahtarlarının isteklerin kimliğini doğruladığını ve bağlantının hangi kaynaklara erişeceğini belirlediğini söyler. Yalnızca ihtiyacınız olan yetkiyi veren ayrı bir anahtar açabiliyor musunuz, yoksa tek bir anahtar her şeye mi izin veriyor?
  3. Hız sınırı (rate limit) var mı? Örneğin GitHub’ın dokümanına göre GitHub’ın REST API’sine belirli bir süre içinde yapabileceğiniz istek sayısı sınırlıdır ve sınır kimlik doğrulama yöntemine göre değişir. Geçmiş siparişleri tek seferde aktarırken ya da sık sık soran bir akış kurarken bu sınıra takılabilirsiniz.
  4. Webhook var mı ve hangi olaylar için? Örneğin Shopify’da bu olay türlerine “topic” (konu) denir ve sipariş oluşturma için ayrı bir konu vardır. Sipariş oluşturma, iptal ve iade gibi sizin süreciniz için gereken olaylar listede var mı?
  5. Test ortamı ve hata davranışı. Stripe’ın dokümanı canlı moddan ayrı bir test ortamı (sandbox) anlatır; canlı verilere dokunmadan denemek için böyle bir ortam olup olmadığını sorun. Mesaj ulaşmazsa karşı sistemin ne yaptığı da dokümanda yazmalıdır; aşağıda ayrıca değiniyoruz.

API anahtarı neden gizli tutulur

API anahtarı, programınızın kimliğidir. Anahtarı eline geçiren, ürünün izin verdiği ölçüde sizin adınıza istek yapabilir. Stripe’ın anahtar sayfası bunu açıkça ayırır. Ziyaretçinin tarayıcısına giden, herkesin görebileceği kodda bulunabilecek “publishable” anahtarlar vardır, ama gizli anahtar tüm Stripe API’lerinde kısıtsız yetkiye sahiptir ve açığa çıkarılmamalıdır. Bu yüzden sayfa, yeni kullanımlar için yetkisi sınırlanabilen “restricted” anahtarı öneriyor. Aynı sayfa, anahtarın ele geçirilmesi ya da bir çalışanın ayrılması gibi durumlarda anahtarın yenilenmesini (rotate) önerir.

Pratikte bunun anlamı şudur:

  • Anahtarı e-postaya, sohbet uygulamasına ya da herkesin gördüğü bir tabloya yazmayın.
  • Her bağlantı için ayrı ve mümkün olduğunca dar yetkili bir anahtar isteyin; böylece birini iptal etmek hepsini durdurmaz.
  • Anahtarın kimin hesabında durduğunu bilin. Hesap ve anahtar sahipliğini otomasyon ajansı nasıl seçilir yazısının ilk bölümünde ele aldık.

Webhook’un da bir gizlisi vardır. Stripe, doğrulama yapılmazsa bir saldırganın uç noktanıza sahte olay gönderip sipariş karşılama gibi işlemleri tetikleyebileceğini yazar ve her olayın imzasının doğrulanmasını ister. İmza, mesajın gerçekten o sistemden geldiğini gösteren koddur; Stripe’ta bu imzayı doğrulamakta kullanılan gizli değer API anahtarlarından ayrıdır. Shopify da her mesajla birlikte bir imza (dokümandaki adıyla HMAC imzası) geldiğini ve doğrulanması gerektiğini söyler. Yani webhook adresine kimin mesaj gönderdiğini kontrol etmeyen bir kurulum eksiktir. Webhook alan bir akışı n8n’de adım adım kurmak isterseniz ilk n8n akışı yazısında webhook adresini korumanın n8n’deki seçenekleri de geçiyor.

Çağrı başarısız olunca: yeniden deneme ve kayıt

Bağlantılar bozulur: karşı sistem yanıt vermez, sınır aşılır, mesaj yolda kaybolur. Önemli olan, bozulduğunda ne olduğunu önceden bilmektir.

API tarafında sık karşılaşılan bir durum hız sınırıdır. GitHub örneğinde, dokümana göre sınır aşıldığında 403 ya da 429 kodlu bir hata yanıtı gelir ve sınır sıfırlanana kadar yeniden denememeniz istenir. Doküman, sınırdayken istek göndermeyi sürdürmenin bağlantınızın engellenmesine yol açabileceğini de belirtiyor. İstek, GitHub’ın “ikincil” dediği ek sınırlar yüzünden başarısız olmayı sürdürürse doküman, denemeler arasındaki bekleme süresini giderek artırmayı ve belli sayıda denemeden sonra hata vermeyi öneriyor. Yani başarısız çağrıyı hemen yeniden göndermek çözüm değildir.

Webhook tarafında karşı sistem genellikle yeniden dener. Stripe, olayları canlı modda üç güne kadar giderek artan aralıklarla yeniden göndermeye çalıştığını yazar. Ama bunun iki sonucu var. Birincisi, aynı olay iki kez gelebilir: Stripe işlenen olayların kimliğini kaydetmeyi, Shopify da mesajla gelen kimliğe bakarak mükerrer teslimleri yok saymayı önerir. Siparişi iki kez faturalamamak için sipariş numarası gibi benzersiz bir anahtarla “bu kayıt işlendi mi” diye bakmak gerekir. İkincisi, sıra garanti değildir: iki dokümanda da olayların üretildikleri sırayla gelmeyebileceği yazar. Üstelik Shopify teslimatın her zaman garanti edilmediğini söyler; yedek olarak aralıklı bir uzlaştırma önerir.

Bu yüzden her bağlantıda iki şey olmalı: bir hata bildirimi ve bir kayıt. Hata bildirimi “bir adım başarısız oldu” haberini adı belli bir kişiye taşır. Kayıt ise hangi siparişin işlenmediğini gösterir; olmazsa kimin neyi kaçırdığını bilemezsiniz. Biz kurduğumuz her akışı bu ikisiyle açıyoruz; ayrıntıyı otomasyon ve yapay zeka hizmeti sayfasında bulabilirsiniz. Bağlandığınız sistem API’sini değiştirdiğinde akışın da güncellenmesi gerektiğini, aylık gözden geçirmede bu tür değişiklikleri yakalamaya çalıştığımızı da orada yazıyoruz.

Satıcıya sorulacak sorular

Satın alma görüşmesinde şu soruları sorun ve cevapları yazılı isteyin:

  1. Ürünün arayüzünde yapılan hangi işler API’den de yapılabiliyor? Listesi nerede?
  2. Kimlik doğrulama hangi yöntemle yapılıyor? Yalnızca gereken yetkiyi veren ayrı bir anahtar açabilir miyim?
  3. Hız sınırı nedir, aşılınca ne oluyor? Sınır kullandığım pakete göre değişiyor mu?
  4. Hangi olaylar için webhook var? Mesaj ulaşmazsa yeniden deneniyor mu, ne kadar süreyle?
  5. Test ortamı var mı? Gönderilen mesajları ve hataları bir ekrandan geçmişe dönük görebilir miyim?
  6. API’de değişiklik olursa bunu nasıl ve ne kadar önceden duyuruyorsunuz?

Eski bir muhasebe ya da ERP programınız varsa ve cevaplar “API yok” çıkarsa durum kapanmış sayılmaz. Biz süreç envanterinde programın veriyi nasıl dışarı verdiğine bakıyoruz: düzenli dosya aktarımı, veritabanı erişimi ya da e-postayla gelen raporlar bir giriş noktası olabilir. Güvenilir bir yol yoksa bunu açıkça söyleyip o adımı insanda bırakıyoruz. Pazaryeri bağlantılarında API’nin rolünü pazaryeri entegrasyonu nedir yazısında anlattık.

Sık yapılan hatalar

  • Yalnızca “API’miz var” cevabıyla yetinmek. Var olan API sizin işlemi kapsamayabilir; kapsamı isteyin.
  • Webhook’a tek başına güvenmek. Teslimat her üründe garanti edilmez; aralıklı bir kontrol ekleyin.
  • Hız sınırına bakmadan toplu aktarım başlatmak. Sınıra takılan akış yarım kalır.
  • Yeniden denemelerde mükerrer kayıt üretmek. Benzersiz bir anahtarla kontrol etmeyen akış aynı siparişi iki kez yazar.
  • Anahtarı ortak bir yere yazmak. Anahtar ortak bir yerde duruyorsa, bir çalışan ayrıldığında kimin neyi bildiğini takip edemezsiniz.

Sık sorulanlar

API ile webhook arasındaki fark nedir?

API’de bağlanmak isteyen taraf sorar ve karşı sistem cevap verir. Webhook’ta ise karşı sistem, bir olay olunca önceden verilmiş adrese kendiliğinden mesaj gönderir. Yani fark, konuşmayı kimin başlattığıdır.

Webhook mu kullanmalıyım, API mi?

Bir olay olur olmaz bir işin başlamasını istiyorsanız (yeni sipariş, ödeme sonucu) webhook uygundur. Geçmiş verileri çekmek, kayıt oluşturmak ya da kaçan olayları yakalamak için API gerekir. Çoğu bağlantı ikisini birlikte kullanır.

API anahtarı sızdıysa ne yapılır?

Anahtarı hemen iptal edip yenisini oluşturun ve yeni anahtarı bağlantıya tanıtın. Stripe’ın dokümanı, ele geçirilmiş bir anahtarın geçersiz kılınmasını ve değiştirilmesini önerir. Ürün istek kayıtlarını tutuyorsa (Stripe’ın anahtar sayfası, her anahtarın istek kayıtlarının Workbench’te görülebildiğini yazar) sızıntı döneminde anahtarla neler yapıldığına bakın.

Bugün yapabileceğiniz iş şu: bağlamak istediğiniz iki programdan birinin dokümantasyonunu açın ve arama kutusuna “webhook”, “rate limit” ve “authentication” yazın. Üçü için de bir sayfa bulmanız, ürünün dışarıya açık olduğuna dair iyi bir işarettir. Bulamazsanız yukarıdaki altı soruyu satıcıya yazılı olarak gönderin.

Kaynaklar

Bu yazı genel bilgi vermek için hazırlandı; hukuki, mali ya da teknik danışmanlık yerine geçmez. Platformlar, kuralları ve mevzuat zamanla değişir; 11 Kasım 2026 tarihinden bu yana değişmiş ya da küçük hatalar içeren bilgiler olabilir. İşinizle ilgili bir karar vermeden önce güncel resmi kaynakları kontrol edin ya da bize yazın.

Diğer yazılar

Projenizi
anlatın.

Formu doldurun ya da doğrudan yazın; görüşme gününü birlikte belirleriz.

İlk görüşmeyi Detmore’un kurucusu Deniz Sezer yapar.

İlk görüşme ücretsiz · Bir iş gününde yanıt · 2 ila 3 günde yazılı teklif · NDA hazır

Neye ihtiyacınız var? birden fazla seçebilirsiniz

Ad, e-posta ve telefon zorunludur.

İletişim

Bir iş günü içinde dönüyoruz.