- Konu sahibi
- #1
Webhook, bir uygulamada gerçekleşen olayı başka bir uygulamaya HTTP isteği göndererek bildiren olay tabanlı entegrasyon mekanizmasıdır; gecikme veya teslimat kaybı olabileceği için kesin anlık teslim garantisi değildir. Örneğin ödeme uygulaması bir işlemin tamamlandığını kendi sunucunuzda tanımlı webhook adresine bildirir. Böylece sizin uygulamanız sürekli olarak “Yeni bir sonuç oluştu mu?” diye sorgulama yapmak yerine, olay gerçekleştiğinde gelen bildirimi işler.
Webhook genellikle bir HTTP veya HTTPS uç noktasına gönderilen
Webhook akışında iki taraf bulunur: olayı üreten servis ve bildirimi alan uygulama. Alan uygulama önce erişilebilir bir uç nokta hazırlar. Üreten servis, olay oluştuğunda bu adrese istek gönderir. Alıcı istek gövdesini okur, kaynağın gerçekten beklenen servis olduğunu kontrol eder, işlemi mümkünse hızlıca kuyruğa bırakır ve başarılı yanıt verir.
Örnek olarak bir SaaS uygulamasında yeni sipariş oluşturulduğunu düşünelim. Sipariş servisi şu tür bir veri gönderebilir:
Bu isteği alan uygulama,
Webhook ile düzenli sorgulama arasındaki temel fark aşağıdaki gibidir:
Bu nedenle olayın hızlı bildirilmesi gereken ve karşı servis tarafından desteklenen durumlarda webhook daha uygun olabilir. Olay kaçırıldığında sonradan kontrol edebilmek önemliyse webhook'un yanında periyodik senkronizasyon veya servis API'sinden yeniden sorgulama da tasarlanabilir.
Webhook isteğini yalnızca gövde biçimine bakarak güvenilir kabul etmeyin. Sağlayıcının imza doğrulamasını, gizli anahtarını veya doğrulama başlığını kullanın. Ayrıca gelen isteğin zaman damgasını ve beklenen olay türünü kontrol etmek, eski veya hatalı isteklerin işlenmesini azaltır.
Aynı olayın birden fazla kez gelmesi normal bir hata senaryosudur. Ağ bağlantısı koptuğunda gönderen servis, sizin işlemi yaptığınızı bilmeden bildirimi yeniden gönderebilir. Bu yüzden işlem kimliğine göre idempotent bir akış kurun: aynı
İlk yanıtı verdikten sonra uzun süren e-posta gönderme, dosya işleme veya üçüncü taraf API çağrıları gibi işleri arka planda yürütmek daha sağlıklıdır. Başarısız olayları kaydedin; sağlayıcı yeniden göndermiyorsa yönetici panelinden veya ayrı bir tekrar deneme kuyruğundan kontrollü biçimde işleyin.
Teslimat sırası garanti edilmeyebilir; eski olayı yeni durumun üstüne yazmayın. Gerekirse kaynağın güncel nesnesini API’den alın ve iş durumu geçişini doğrulayın. Sağlayıcıların retry süresi, olay biçimi ve imza yöntemi farklıdır. Örnekteki order.created/status alanları temsili bir sağlayıcı sözleşmesidir; her servisin gerçek alanı aynı değildir. Webhook, API’nin karşıtı değil API entegrasyonunda kullanılan ters yöndeki bildirim akışıdır.
Sadece başarılı yanıtı düşünmek: Alıcı uygulama hata durumunda ne yapacağını belirlemezse olay kaybolabilir veya sonsuz tekrar oluşabilir. Hata kaydı ve tekrar deneme politikası tanımlayın.
İmza doğrulamadan işlem yapmak: Herkesin erişebildiği uç noktaya gönderilen sahte bir istek gerçek sipariş, üyelik veya ödeme akışını tetikleyebilir.
Tekrar gönderimi yok saymak: Aynı webhook iki kez geldiğinde iki kayıt oluşturmak veri tutarsızlığına yol açar. Benzersiz olay kimliğini veritabanında izleyin.
İşlemi HTTP isteği içinde bitirmeye çalışmak: Uzun işlem süreleri zaman aşımına neden olabilir. Önce bildirimi güvenli biçimde kaydedin, sonra arka plan işçisiyle tamamlayın.
Gözlemleme eklememek: Olay türünü, olay kimliğini, işlem sonucunu ve hata nedenini günlüğe yazın; ancak parolaları, imza anahtarlarını ve gereksiz kişisel verileri günlüğe aktarmayın.
API çoğunlukla sizin bir servisten veri veya işlem istemeniz için çağrılır. Webhook'ta ise servis, belirli bir olay gerçekleştiğinde sizin belirlediğiniz uç noktaya kendiliğinden bildirim gönderir. Bir uygulama ikisini birlikte kullanabilir.
Önce uç noktanın dışarıdan erişilebilir olup olmadığını, HTTPS ve HTTP durum kodunu kontrol edin. Ardından sağlayıcının gönderim günlüklerine, uygulamanızın istek kayıtlarına, imza doğrulama sonucuna ve olayın daha önce işlenip işlenmediğine bakın.
Bu, sağlayıcının yeniden gönderim ve olay geçmişi özelliklerine bağlıdır. Güvenilir tasarımda gelen olayın gerekli kısmı kendi sisteminizde saklanır; böylece yalnızca geçici bir bildirime bağımlı kalmadan işlemi yeniden deneyebilirsiniz.
Webhook genellikle bir HTTP veya HTTPS uç noktasına gönderilen
POST isteğidir. İstek gövdesinde olay türü, ilgili kaydın kimliği ve olayla ilgili veriler bulunur. Alıcı uygulama isteği doğrular, veriyi işler ve başarılı aldığını belirtmek için uygun bir HTTP durum kodu döndürür.Nasıl çalışır?
Webhook akışında iki taraf bulunur: olayı üreten servis ve bildirimi alan uygulama. Alan uygulama önce erişilebilir bir uç nokta hazırlar. Üreten servis, olay oluştuğunda bu adrese istek gönderir. Alıcı istek gövdesini okur, kaynağın gerçekten beklenen servis olduğunu kontrol eder, işlemi mümkünse hızlıca kuyruğa bırakır ve başarılı yanıt verir.
Örnek olarak bir SaaS uygulamasında yeni sipariş oluşturulduğunu düşünelim. Sipariş servisi şu tür bir veri gönderebilir:
Kod:
{
"event": "order.created",
"event_id": "evt_12345",
"order_id": "ord_789",
"status": "paid"
}Bu isteği alan uygulama,
event değerine göre siparişi kendi veritabanına aktarabilir. event_id için sağlayıcı/hesap kapsamıyla benzersiz kayıt ve atomik işleme kurarsa aynı olayın tekrarında siparişin ikinci kez oluşmasını önleyebilir. Önce sorgula-sonra ekle şeklinde yarışa açık bir kontrol yeterli değildir.Webhook ile düzenli sorgulama arasındaki temel fark aşağıdaki gibidir:
| Özellik | Webhook | Düzenli sorgulama |
|---|---|---|
| Tetikleme | Olay gerçekleşince | Belirli aralıklarla |
| Gecikme | Genellikle daha düşüktür | Sorgulama aralığına bağlıdır |
| İstek yönü | Servis, sizin uç noktanıza gönderir | Sizin uygulamanız servisi çağırır |
| Dikkat edilmesi gereken konu | Tekrar gönderim ve doğrulama | Gereksiz istek ve kota kullanımı |
Bu nedenle olayın hızlı bildirilmesi gereken ve karşı servis tarafından desteklenen durumlarda webhook daha uygun olabilir. Olay kaçırıldığında sonradan kontrol edebilmek önemliyse webhook'un yanında periyodik senkronizasyon veya servis API'sinden yeniden sorgulama da tasarlanabilir.
Webhook kullanmak için temel adımlar
- Alıcı uygulamanızda bir uç nokta oluşturun. Örneğin
POST /webhooks/ordersadresi yalnızca webhook bildirimlerini kabul etsin. - Üreten serviste bu uç noktanın tam adresini ve dinlenecek olayları tanımlayın. HTTPS kullanılması, bildirimin aktarım sırasında korunması için temel önkoşuldur.
- Gelen isteğin imzasını veya sağlayıcının sunduğu doğrulama yöntemini kontrol edin. İmza doğrulanamıyorsa veriyi işleme almayın.
- İstek gövdesindeki olay türünü ve benzersiz olay kimliğini okuyun. Daha önce işlenmiş bir olay kimliği varsa aynı işlemi tekrar etmeyin.
- Gerekli veriyi kalıcı olarak kaydedin ve asıl işi bir kuyrukta veya arka plan görevinde yürütün. Webhook isteğini uzun süre açık tutmak, gönderen servisin zaman aşımına uğramasına neden olabilir.
- İstek başarıyla kaydedildikten sonra sağlayıcının beklediği başarılı HTTP yanıtını döndürün. İşlem başarısızsa hatayı günlüğe yazın ve yeniden gönderim davranışını kontrol edin.
- Test olayını göndererek uç noktanın doğrulama, kayıt, tekrar çalıştırma ve hata durumlarını denetleyin. Başarılı testte olayın beklenen kayda dönüştüğünü doğrulayın.
Güvenilir bir webhook alıcısında dikkat edilecekler
Webhook isteğini yalnızca gövde biçimine bakarak güvenilir kabul etmeyin. Sağlayıcının imza doğrulamasını, gizli anahtarını veya doğrulama başlığını kullanın. Ayrıca gelen isteğin zaman damgasını ve beklenen olay türünü kontrol etmek, eski veya hatalı isteklerin işlenmesini azaltır.
Aynı olayın birden fazla kez gelmesi normal bir hata senaryosudur. Ağ bağlantısı koptuğunda gönderen servis, sizin işlemi yaptığınızı bilmeden bildirimi yeniden gönderebilir. Bu yüzden işlem kimliğine göre idempotent bir akış kurun: aynı
event_id daha önce işlendiğinde yeni kayıt oluşturmak yerine başarılı yanıt verin.İlk yanıtı verdikten sonra uzun süren e-posta gönderme, dosya işleme veya üçüncü taraf API çağrıları gibi işleri arka planda yürütmek daha sağlıklıdır. Başarısız olayları kaydedin; sağlayıcı yeniden göndermiyorsa yönetici panelinden veya ayrı bir tekrar deneme kuyruğundan kontrollü biçimde işleyin.
Teslimat sırası garanti edilmeyebilir; eski olayı yeni durumun üstüne yazmayın. Gerekirse kaynağın güncel nesnesini API’den alın ve iş durumu geçişini doğrulayın. Sağlayıcıların retry süresi, olay biçimi ve imza yöntemi farklıdır. Örnekteki order.created/status alanları temsili bir sağlayıcı sözleşmesidir; her servisin gerçek alanı aynı değildir. Webhook, API’nin karşıtı değil API entegrasyonunda kullanılan ters yöndeki bildirim akışıdır.
Sık yapılan hatalar
Sadece başarılı yanıtı düşünmek: Alıcı uygulama hata durumunda ne yapacağını belirlemezse olay kaybolabilir veya sonsuz tekrar oluşabilir. Hata kaydı ve tekrar deneme politikası tanımlayın.
İmza doğrulamadan işlem yapmak: Herkesin erişebildiği uç noktaya gönderilen sahte bir istek gerçek sipariş, üyelik veya ödeme akışını tetikleyebilir.
Tekrar gönderimi yok saymak: Aynı webhook iki kez geldiğinde iki kayıt oluşturmak veri tutarsızlığına yol açar. Benzersiz olay kimliğini veritabanında izleyin.
İşlemi HTTP isteği içinde bitirmeye çalışmak: Uzun işlem süreleri zaman aşımına neden olabilir. Önce bildirimi güvenli biçimde kaydedin, sonra arka plan işçisiyle tamamlayın.
Gözlemleme eklememek: Olay türünü, olay kimliğini, işlem sonucunu ve hata nedenini günlüğe yazın; ancak parolaları, imza anahtarlarını ve gereksiz kişisel verileri günlüğe aktarmayın.
Kaynaklar
Sık sorulan sorular
Webhook ile API arasındaki fark nedir?
API çoğunlukla sizin bir servisten veri veya işlem istemeniz için çağrılır. Webhook'ta ise servis, belirli bir olay gerçekleştiğinde sizin belirlediğiniz uç noktaya kendiliğinden bildirim gönderir. Bir uygulama ikisini birlikte kullanabilir.
Webhook çalışmazsa ilk neresi kontrol edilmelidir?
Önce uç noktanın dışarıdan erişilebilir olup olmadığını, HTTPS ve HTTP durum kodunu kontrol edin. Ardından sağlayıcının gönderim günlüklerine, uygulamanızın istek kayıtlarına, imza doğrulama sonucuna ve olayın daha önce işlenip işlenmediğine bakın.
Webhook ile gönderilen veriyi sonradan tekrar alabilir miyim?
Bu, sağlayıcının yeniden gönderim ve olay geçmişi özelliklerine bağlıdır. Güvenilir tasarımda gelen olayın gerekli kısmı kendi sisteminizde saklanır; böylece yalnızca geçici bir bildirime bağımlı kalmadan işlemi yeniden deneyebilirsiniz.
