Yan yana

APIvsWebhook

API ile webhook arasındaki fark nedir?

Güncellendi 6 Ekim 20262 dk okuma8 fark

Kısaca

API'de uygulamanız veri istediği an bir istek gönderir; webhook'ta ise bir olay olur olmaz başka bir servis sizin URL'inize bir istek gönderir.

Backend ve API'lers. 2

API

Uygulama Programlama Arayüzü

API, bir yazılımın başka bir yazılımdan veri ya da işlem talep etmesini sağlayan, belgelenmiş ve öngörülebilir kurallar bütünüdür.

API sayfasını oku

Backend ve API'lers. 51

Webhook

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 sayfasını oku

API ve Webhook karşılaştırması

Özellik	API	Webhook
Yön	Uygulamanız servisi çağırır	Servis uygulamanızı çağırır
Tetikleyici	Ne zaman soracağına kodunuz karar verir	Diğer sistemde gerçekleşen bir olay
Zamanlama	Ne zaman sorarsanız; değişiklikleri fark etmek polling gerektirir	Olaydan saniyeler sonra
Sizin sağladığınız	Her istekle bir API anahtarı ya da token	`POST` isteklerini kabul eden herkese açık bir URL
Veri	Ne isterseniz: okuma, oluşturma, güncelleme ya da silme	Tek bir olayı anlatan bir bildirim
Hata yönetimi	Hatayı yanıtta görür, yeniden deneyebilirsiniz	Gönderen yeniden dener; tekrarları sizin ele almanız gerekir
Güvenlik	Servis sizin kimliğinizi doğrular	Gönderenin kimliğini, genellikle bir imzayla, siz doğrularsınız
Tipik kullanım	İhtiyaç anında veriyi okumak ve değiştirmek	Ödeme onayları, Git push'ları, form gönderimleri

Fark, açıklamalı

API, bir servisin sunduğu işlemler bütünüdür: uygulamanız bir siparişi okumak ya da bir ödeme oluşturmak gibi bir şeye ihtiyaç duyduğunda onu çağırır ve hemen bir yanıt alır. Webhook ise yönü tersine çevirir. Bir servise bir URL verirsiniz; başarılı bir ödeme ya da bir depoya yapılan push gibi ilgilendiğiniz bir olay gerçekleştiğinde servis, ayrıntılarla birlikte o URL'e bir HTTP POST isteği gönderir.

Webhook'lara bu yüzden bazen ters API (reverse API) denir. Yalnızca bir API ile değişikliklerden haberdar olmak polling demektir: yeni bir şey olup olmadığını tekrar tekrar sormak; bu da istekleri boşa harcar ve haberi polling aralığı kadar geciktirebilir. Webhook ise olayı saniyeler içinde ve yalnızca söylenecek bir şey olduğunda iletir.

İkisi alternatiften çok ortaktır. Bir webhook için kaydettiğiniz URL aslında diğer servisin çağırdığı, size ait küçük bir API endpoint'idir; çoğu servis de ikisini birden sunar: bir şeyin olduğunu duyurmak için webhook'lar, tüm ayrıntıları çekmek ya da üzerine işlem yapmak için bir API. Tipik bir işleyici bir webhook alır, onu denetler, ardından en güncel durum için gönderenin API'sini çağırır.

Webhook'lar kendi sorumluluklarını da getirir. URL herkese açık olduğu için alıcı her teslimatı, genellikle paylaşılan bir sırla oluşturulmuş bir imza üzerinden doğrulamalıdır. Gönderenler başarısız teslimatları yeniden dener; bu yüzden aynı olay iki kez ya da sırasız gelebilir ve işleyici hızla bir 2xx durumuyla cevap verip asıl işi arka planda yapmalıdır.

Hangisini kullanmalısınız?

API şu durumlarda doğru seçim:

Uygulamanızın kendi seçtiği bir anda veriye ihtiyacı var ya da bir işlem yapması gerekiyor.
Yalnızca değiştiğine dair bir bildirime değil, bir şeyin tam ve güncel durumuna ihtiyacınız var.
Uygulamanız, bir mobil uygulama ya da güvenlik duvarının arkasındaki bir betik gibi, herkese açık bir URL sunamıyor.

Webhook şu durumlarda doğru seçim:

Başka bir sistemde bir şey olduğunda hızla tepki vermeniz gerekiyor.
Polling istekleri boşa harcar ya da hız sınırlarına takılır.
Yeniden denemeleri ve tekrarları ele alan, herkese açık ve güvenli bir endpoint işletebiliyorsunuz.

Bir API'yi yoklamak ile bir webhook almak (Node.js)

APIjavascript

// API: your app asks, here every minute, whether the payment went through
setInterval(async () => {
  const res = await fetch(`https://api.pay.example/payments/${paymentId}`, {
    headers: { Authorization: `Bearer ${API_KEY}` },
  });
  const payment = await res.json();
  if (payment.status === "succeeded") markOrderAsPaid(payment.orderId);
}, 60_000);

Webhookjavascript

// Webhook: the provider calls your URL the moment the payment succeeds
app.post("/webhooks/payments", express.raw({ type: "application/json" }), (req, res) => {
  if (!isValidSignature(req)) return res.sendStatus(400); // shared-secret check

  const event = JSON.parse(req.body);
  if (event.type === "payment.succeeded") markOrderAsPaid(event.data.orderId);

  res.sendStatus(200); // answer quickly, or the sender will retry
});

Sık sorulan sorular

Webhook bir API midir?

Bir bakıma evet. Webhook, bir sistemin başka bir sistemin endpoint'ine gönderdiği bir HTTP isteğidir; yani isteği alan URL küçücük bir API'dir. Fark, çağrıyı kimin başlattığıdır: webhook'ta bunu sağlayıcı yapar.

Webhook mu polling mi, hangisi daha iyi?

Webhook'lar daha az istekle zamanında güncelleme sağlar; polling ise gelen istekleri alamadığınızda ya da basit bir yedek yönteme ihtiyaç duyduğunuzda işe yarar. Pek çok entegrasyon ikisini birleştirir ve kaçırılmış webhook'ları yakalamak için arada bir polling yapar.

Bir webhook endpoint'ini nasıl güvenli hâle getiririm?

HTTPS kullanın, imza başlığını paylaşılan sırla doğrulayın, tekrar saldırılarını (replay) durdurmak için eski zaman damgalarını reddedin ve tekrarlanan bir olay zarar vermesin diye işleyiciyi idempotent yapın.