Bir platforma webhook özelliği eklemek genellikle şöyle başlar:

Bir olay gerçekleşir.

Kullanıcının kaydettiği URL’ye HTTP isteği gönderilir.

POST https://customer.example/hooks
{ "type": "invoice.paid", "id": "evt_81f2" }

Bu kadar.

İlk müşteri entegrasyonu çalışır. Sonra destek talepleri gelmeye başlar.

“Dün bir ödeme bildirimi almadık.”

“Aynı bildirim iki kez geldi.”

“Bu isteğin sizden geldiğini nasıl anlayacağız?”

Karşı taraf her zaman ayakta değildir

Webhook alan sistem deploy oluyor olabilir. Yavaş cevap veriyor olabilir. Bir saatlik bakım çalışmasında olabilir.

Webhook gönderen taraf bunu normal kabul etmeli.

Bu yüzden webhook gönderimi, olayın oluştuğu isteğin içinde senkron olarak yapılmamalı. Olay önce kalıcı olarak kaydedilmeli ve ayrı bir worker tarafından gönderilmeli. Ödeme işleminin cevabı, müşterinin webhook endpoint’inin yavaşlığından etkilenmemeli.

Retry ve backoff

2xx dışındaki her cevap veya timeout başarısız kabul edilir ve tekrar denenir.

Ama hemen değil. Artan aralıklarla:

1 dakika
5 dakika
30 dakika
2 saat
...
toplam ~3 gün

Birkaç günlük bir retry penceresi, karşı tarafın uzun bir kesintiden sonra bile olayları almasını sağlar.

Bir endpoint uzun süre sürekli başarısız oluyorsa, müşteriye bildirim gönderip endpoint’i devre dışı bırakmak da gerekebilir. Aksi halde worker’lar ölü bir adrese sonsuza kadar istek atar.

Timeout değeri de kısa tutulmalı. Webhook alan tarafın işi uzun sürecekse, isteği hemen kabul edip işi arka planda yapması beklenir. Stripe ve GitHub gibi platformlar da dokümantasyonlarında hızlıca 2xx dönülmesini öneriyor.

Aynı olay birden fazla gelebilir

Webhook gönderildi. Karşı taraf işledi. Ama cevap ağda kayboldu.

Gönderen taraf timeout gördüğü için tekrar gönderir.

Webhook’lar at-least-once teslim edilir. Bu kaçınılmaz.

Bu yüzden her olayın benzersiz ve değişmeyen bir ID’si olmalı. Alan taraf bu ID’yi saklayarak tekrar gelen olayları ayıklayabilmeli.

Gönderen tarafın dokümantasyonunda bunu açıkça yazması da önemli. “Aynı event birden fazla gelebilir, id alanı ile tekilleştirin” cümlesi, birçok entegrasyon hatasını baştan önler.

Sıra garantisi yok

Retry mekanizması olan her sistemde olaylar gönderildiği sırayla ulaşmayabilir.

invoice.paid olayı invoice.created olayından önce gelebilir.

Alan taraf bunu tolere etmeli. Pratik bir yaklaşım, webhook’u sadece “bu kaynakta bir şey değişti” sinyali olarak kullanmak ve güncel durumu API’den okumaktır. Böylece sıra problemi büyük ölçüde ortadan kalkar.

İmza

Webhook endpoint’i internete açık bir URL’dir. Herkes oraya istek gönderebilir.

Alan tarafın isteğin gerçekten platformdan geldiğini doğrulayabilmesi gerekir. En yaygın yöntem, her müşteri için ayrı bir secret ile HMAC imzası üretmektir:

X-Signature: t=1792951200,v1=5257a869e7ecebeda32a...

İmza, zaman damgası ve gövdenin birleşiminden hesaplanır. Alan taraf aynı hesabı yapar ve sonuçları karşılaştırır.

Burada iki detay önemli.

Karşılaştırma constant-time yapılmalı. Basit string karşılaştırması timing attack’a açık olabilir.

Zaman damgası kontrol edilmeli. Birkaç dakikadan eski istekler reddedilirse, yakalanmış bir isteğin daha sonra tekrar oynatılması engellenir.

İmza ham gövde üzerinden doğrulanmalı. JSON parse edilip tekrar serialize edilen gövde, boşluk veya alan sırası farkı nedeniyle farklı bir imza üretir. Framework’ler bazen gövdeyi otomatik parse ettiği için bu, en sık karşılaşılan doğrulama hatalarından biri.

Gözlemlenebilirlik müşteriye de lazım

İyi bir webhook sistemi, müşterinin kendi tarafında olanları görebilmesini sağlar. Gönderilen olayların listesi, cevap kodları, deneme sayısı ve manuel olarak tekrar gönderme butonu.

Bu ekran, destek ekibine gelen “bildirim gelmedi” taleplerinin büyük kısmını ortadan kaldırır.

Webhook basit bir HTTP isteği gibi görünüyor.

Ama aslında iki farklı şirketin sistemleri arasında kurulan dağıtık bir mesajlaşma kanalı ve öyle tasarlanması gerekiyor.