Tobias Hoffmann

Posted on Jul 3 • Originally published at apidog.com

Webhook ve API: Gerçek Fark Nedir?

“Webhook vs API” araması genelde şu pratik soruya çıkar: Bir entegrasyonda veriyi ben mi istemeliyim, yoksa sistem bana olay olduğunda mı haber vermeli? Kısa cevap: Webhook, API’nin alternatifi değildir; HTTP üzerinden çalışan, yönü tersine dönmüş bir iletişim modelidir.

Apidog'u bugün deneyin

Bu yazıda REST API ve webhook arasındaki farkı, hangi durumda hangisini kullanmanız gerektiğini ve ikisini birlikte nasıl tasarlayıp test edebileceğinizi göreceksiniz. Entegrasyon geliştiriyorsanız, Apidog ile normal API uç noktalarını ve webhook alıcılarını aynı çalışma alanında tasarlayabilir, simüle edebilir ve test edebilirsiniz.

Kısa cevap

Normal API çağrısı: Siz istek gönderirsiniz, servis yanıt döner. Zamanlamayı istemci belirler.
Webhook: Servis, kendi tarafında bir olay olduğunda sizin URL’nize istek gönderir. Zamanlamayı sağlayıcı belirler.
İkisi de çoğunlukla HTTP ve JSON kullanır.
Bu yüzden webhook için sıkça “reverse API”, “push API” veya “ters API” denir.

Özetle konu “webhook vs API” değil, pull vs push modelidir.

API derken genelde ne kastedilir?

Bir geliştirici “API’yi çağır” dediğinde çoğunlukla REST tarzı bir istek-cevap akışından bahseder.

Örneğin sipariş durumunu almak için:

GET /orders/123 HTTP/1.1
Host: api.example.com
Authorization: Bearer <token>

Yanıt:

{
  "id": "123",
  "status": "paid",
  "total": 2499
}

Bu modelde kontrol sizdedir:

Ne zaman veri istediğinize karar verirsiniz.
API’ye istek gönderirsiniz.
Yanıtı işler ve uygulamanızda kullanırsınız.

Bu, pull modelidir. İsteğe bağlı veri almak, kullanıcı aksiyonu çalıştırmak veya rapor üretmek için uygundur.

Dezavantajı şudur: Bir değişikliği yakalamak için sürekli sormanız gerekir. Örneğin ödeme tamamlandı mı diye her 5 saniyede bir kontrol etmek çoğu zaman gereksiz yük oluşturur.

API isteğinin nasıl yapılandığını daha detaylı görmek için API istek yapısını anlama yazısına bakabilirsiniz.

Webhook nedir?

Webhook, sizin tanımladığınız bir HTTP callback URL’sidir.

Örneğin Stripe için şöyle bir endpoint yayınlarsınız:

https://uygulamaniz.com/webhooks/stripe

Ardından bu URL’yi sağlayıcıya kaydedersiniz. Sağlayıcı tarafında bir olay gerçekleştiğinde, örneğin ödeme başarılı olduğunda, sağlayıcı sizin endpoint’inize bir POST isteği gönderir.

Örnek webhook isteği:

POST /webhooks/stripe HTTP/1.1
Host: uygulamaniz.com
Content-Type: application/json
Stripe-Signature: t=...,v1=...

{
  "type": "payment_intent.succeeded",
  "data": {
    "object": {
      "id": "pi_123",
      "amount": 2499,
      "currency": "try",
      "status": "succeeded"
    }
  }
}

Bu modelde siz arayan değil, alıcısınız. Sunucunuz bekler; sağlayıcı olay olduğunda size veri gönderir.

Bu, push modelidir.

Webhook’lar örneğin:

Stripe ödeme durumlarını bildirmek için,
GitHub push, pull request veya issue olaylarını bildirmek için,
Slack komut ve etkileşimlerini uygulamanıza iletmek için kullanılır.

Alıcı tarafını nasıl tasarlayacağınızı görmek için webhook API nedir yazısına bakabilirsiniz.

Webhook vs API: Temel fark

Kriter	Normal API / REST	Webhook
Çağrıyı kim başlatır?	Siz, yani istemci	Sağlayıcı
Model	İstek-cevap / pull	Olay odaklı / push
Zamanlama	Siz ne zaman çağırırsanız	Olay gerçekleştiğinde
Yön	Sizin sisteminiz sağlayıcıyı çağırır	Sağlayıcı sizin endpoint’inizi çağırır
En uygun kullanım	İsteğe bağlı veri alma ve aksiyon başlatma	Tahmin edilemeyen olaylara tepki verme
Ana maliyet	Değişiklikler için polling gerekebilir	Public endpoint yayınlamanız ve güvenceye almanız gerekir

En kritik fark ilk satırdır: çağrıyı kimin başlattığı.

Bu fark; güvenlik, hata yönetimi, retry stratejisi ve test yaklaşımını doğrudan etkiler.

“Webhook sadece bir API değil mi?”

Evet, ama bağlam önemli.

Webhook da API çağrısıyla aynı temel bileşenleri kullanır:

HTTP metodu
URL
Header’lar
JSON body
Status code
Authentication veya signature doğrulama

Bu açıdan webhook da bir HTTP API çağrısıdır. Fakat rolleri değiştirir:

Normal API’de: Sizin uygulamanız istemcidir, sağlayıcı sunucudur.
Webhook’ta: Sağlayıcı istemcidir, sizin uygulamanız sunucudur.

Bu nedenle webhook ayrı bir teknoloji değil, bir API iletişim kalıbıdır.

OpenAPI 3.1 de bu ihtiyacı desteklemek için webhooks alanı sunar. Detaylar için OpenAPI 3.1 spesifikasyonuna ve OpenAPI geri çağrıları ve webhook'lar rehberine bakabilirsiniz.

Ne zaman normal API kullanmalısınız?

Normal API çağrısı şu durumlarda doğru tercihtir:

Kullanıcı bir sayfa açtığında veri göstermeniz gerekiyorsa.
Bir kaydı oluşturmak, güncellemek veya silmek istiyorsanız.
Bir ödeme, mesaj, sipariş veya iş akışı başlatıyorsanız.
Veriyi kendi zamanlamanızda almak istiyorsanız.
Son durumu manuel olarak sorgulamanız gerekiyorsa.

Örnek: Kullanıcı panelinde sipariş detayını göstermek.

async function getOrder(orderId) {
  const response = await fetch(`https://api.example.com/orders/${orderId}`, {
    headers: {
      Authorization: `Bearer ${process.env.API_TOKEN}`
    }
  });

  if (!response.ok) {
    throw new Error("Sipariş alınamadı");
  }

  return response.json();
}

Burada olay beklemiyorsunuz. Kullanıcının isteği üzerine veriyi çekiyorsunuz.

Ne zaman webhook kullanmalısınız?

Webhook şu durumlarda daha uygundur:

Bir olayın gerçekleştiği anı bilmeniz gerekiyorsa.
Olayın ne zaman olacağını tahmin edemiyorsanız.
Sürekli polling yapmak verimsizse.
Sağlayıcı tarafındaki asenkron sürecin sonucunu bekliyorsanız.
Ödeme, dosya işleme, build, deploy, bildirim veya entegrasyon olaylarını dinliyorsanız.

Örnek: Ödeme başarılı olduğunda sipariş durumunu güncellemek.

import express from "express";

const app = express();

app.use(express.json());

app.post("/webhooks/payment", async (req, res) => {
  const event = req.body;

  if (event.type === "payment_intent.succeeded") {
    const payment = event.data.object;

    await markOrderAsPaid(payment.id);
  }

  res.status(200).json({ received: true });
});

async function markOrderAsPaid(paymentId) {
  // Veritabanında ilgili siparişi güncelleyin
  console.log(`Ödeme başarılı: ${paymentId}`);
}

app.listen(3000, () => {
  console.log("Webhook server 3000 portunda çalışıyor");
});

Burada uygulamanız ödeme sonucunu sorgulamaz. Sağlayıcı, sonuç oluştuğunda sizin endpoint’inizi çağırır.

Webhook ve polling arasındaki trade-off için webhook'lar vs yoklama rehberine bakabilirsiniz.

Gerçek entegrasyonlarda ikisi birlikte kullanılır

Webhook ve API çoğu zaman birbirinin yerine geçmez. Birlikte çalışırlar.

Stripe benzeri bir ödeme akışı düşünün:

Uygulamanız ödeme başlatmak için sağlayıcının API’sini çağırır.
Sağlayıcı ödemeyi arka planda işler.
Ödeme başarılı veya başarısız olduğunda sağlayıcı webhook gönderir.
Uygulamanız webhook’u doğrular ve sipariş durumunu günceller.
Gerekirse API çağrısıyla son durumu tekrar teyit eder.

Akış şöyle görünür:

Uygulama  --->  API çağrısı  --->  Ödeme sağlayıcı
Uygulama  <---  Webhook      <---  Ödeme sağlayıcı

Bu tasarım daha güvenilirdir çünkü:

Kullanıcı tarayıcıyı kapatsa bile ödeme sonucu işlenir.
Asenkron süreçler doğru zamanda yakalanır.
Sistemler birbirine gereksiz polling yükü bindirmez.

Daha geniş mimari yaklaşım için olay odaklı API'ler nasıl oluşturulur yazısına bakabilirsiniz.

Webhook endpoint’i tasarlarken dikkat edilmesi gerekenler

Webhook alıcısı sıradan bir endpoint gibi görünür, ancak üretimde birkaç ekstra gereksinimi vardır.

1. Hızlı yanıt dönün

Webhook handler içinde uzun işlem yapmayın. İsteği doğrulayın, olayı kuyruğa alın ve hızlıca 2xx dönün.

app.post("/webhooks/events", async (req, res) => {
  const event = req.body;

  await queue.add("process-webhook", event);

  res.status(202).json({ accepted: true });
});

2. İstekleri doğrulayın

Webhook endpoint’iniz public olacağı için her isteğin gerçekten sağlayıcıdan geldiğini doğrulamalısınız.

Genel yöntemler:

Signature header kontrolü
Shared secret kullanımı
Timestamp kontrolü
Replay attack önleme

Detaylar için Webhook imza doğrulama yazısına bakabilirsiniz.

3. Idempotent işleyin

Webhook sağlayıcıları başarısızlık durumunda aynı olayı tekrar gönderebilir. Bu yüzden aynı event iki kez gelirse sisteminiz yanlış işlem yapmamalıdır.

Örnek kontrol:

app.post("/webhooks/payment", async (req, res) => {
  const event = req.body;

  const alreadyProcessed = await hasProcessedEvent(event.id);

  if (alreadyProcessed) {
    return res.status(200).json({ duplicate: true });
  }

  await processEvent(event);
  await saveProcessedEvent(event.id);

  res.status(200).json({ received: true });
});

4. Doğru status code dönün

Genel pratik:

2xx: Olay alındı ve kabul edildi.
4xx: İstek geçersiz veya doğrulanamadı.
5xx: Geçici sunucu hatası, sağlayıcı retry yapabilir.

5. Log ve observability ekleyin

En azından şunları loglayın:

Event ID
Event type
Timestamp
Signature doğrulama sonucu
İşleme durumu
Hata mesajı

Bu bilgiler retry, duplicate event ve sağlayıcı tarafı debug süreçlerinde kritik olur.

Webhook vs WebSocket vs polling

Bu üç kavram sık karışır:

Webhook vs polling: Polling tekrar tekrar sorar; webhook olay olduğunda haber verir.
Webhook vs WebSocket: Webhook olay başına tek HTTP isteğidir; WebSocket kalıcı, iki yönlü bağlantıdır.
Webhook vs API: Fark, çağrının yönü ve zamanlamasıdır.

Daha detaylı karşılaştırma için webhook vs WebSocket yazısına bakabilirsiniz.

Apidog ile API ve webhook nasıl tasarlanır ve test edilir?

Webhook geliştirmek çoğu zaman normal API testinden daha zordur. Çünkü endpoint’inizin dışarıdan gerçek POST istekleri alması gerekir. Ayrıca sağlayıcılar her zaman sizin istediğiniz anda test olayı üretmeyebilir.

Apidog ile şu işleri aynı çalışma alanında yapabilirsiniz:

REST API endpoint’lerinizi tasarlamak.
Request/response örnekleri oluşturmak.
Test senaryoları ve assertion’lar yazmak.
Webhook alıcınıza özel POST payload’ları göndermek.
Webhook sözleşmesini REST API dokümantasyonuyla birlikte tutmak.
OpenAPI tabanlı dokümantasyon üretmek.

Pratik test akışı:

Webhook endpoint’inizi tanımlayın.
Beklenen JSON payload örneğini oluşturun.
Header’ları ekleyin.
İmzalı veya imzasız test isteği gönderin.
Handler’ın doğru status code döndüğünü kontrol edin.
Veritabanı veya queue tarafında beklenen işlemin çalıştığını doğrulayın.

API ve webhook sözleşmelerini birlikte yönetmek için Apidog'u indirin.

SSS

Bir webhook bir API midir?

Evet, webhook bir API iletişim kalıbıdır. HTTP, URL, header ve JSON body kullanır. Fark, isteği sizin değil sağlayıcının başlatmasıdır.

Webhook’u API olmadan kullanabilir miyim?

Nadiren. Çoğu gerçek iş akışında önce bir API çağrısıyla işlem başlatılır, sonra webhook ile sonuç alınır. Örneğin ödeme oluşturmak için API, ödeme sonucunu almak için webhook kullanılır.

Alıcı tarafını tasarlamak için webhook API nedir yazısına bakabilirsiniz.

Webhook API’den daha hızlı mıdır?

Olaylara tepki verme açısından genellikle evet. Çünkü olay gerçekleştiğinde bildirim alırsınız. Polling’de ise bir sonraki kontrol zamanını beklersiniz.

Ancak isteğe bağlı veri almak için doğrudan API çağrısı daha doğru araçtır.

Webhook REST API’nin yerini alır mı?

Hayır. REST API isteğe bağlı veri ve aksiyonlar için, webhook ise olay bildirimleri için kullanılır. Üretim sistemleri genellikle ikisini birlikte çalıştırır.

Webhook güvenli midir?

Doğru tasarlanırsa güvenli olabilir. Ancak public endpoint açtığınız için mutlaka signature doğrulama, timestamp kontrolü ve idempotency uygulamalısınız.

Detaylar için Webhook imza doğrulama rehberine bakabilirsiniz.

Sonuç

“Webhook vs API” aslında yanlış bir karşılaştırmadır. Normal API’de siz veriyi çekersiniz. Webhook’ta sağlayıcı olay olduğunda size veri iter.

Kural basit:

Zamanlama sizdeyse API çağrısı kullanın.
Zamanlama sağlayıcıdaysa webhook kullanın.
Güvenilir entegrasyonlarda çoğu zaman ikisini birlikte tasarlayın.

API endpoint’lerinizi ve webhook alıcılarınızı aynı yerde tasarlamak, test etmek ve belgelemek için Apidog kullanabilirsiniz.

DEV Community