Daha Güvenli Bir Webhook Alım Katmanı Tasarlayın
Satıcı olayları, sistemleriniz onlara güvenmeye veya bunları kullanmaya hazır olmadan önce ulaşır. Bu kılavuz, her olayı güvenli biçimde doğrulayan, kaydeden, normalleştiren ve yönlendiren pratik bir alım desenini adım adım ele alır.
Satıcı webhook'ları kendi zamanlamalarına göre gelir, sizin zamanlamanıza göre değil. Bir lisans yenileme bildirimi gece yarısı tetiklenir; bir abonelik iptali ekibiniz tam dağıtım yaparken ulaşır. Güvenli yaklaşım 4 adımlı bir alım desenidir: göndereni doğrulayın, ham olayı kaydedin, veriyi normalleştirin, ardından idempotensi gözetilerek yönlendirin. Bu sıra uygulanmazsa olaylar sessizce düşer, iki kez işlenir ya da yük doğrulanmadan önce harekete geçilir.
Ham teslimat neden yeterli değildir
Satıcıların webhook belgelerinin büyük çoğunluğu "uç noktanızı şu adrese yönlendirin" talimatıyla biter. Bu talimat asıl zorlu kısmı atlar: HTTP yanıtı ile iş mantığınızın veriye göre harekete geçtiği an arasında ne olduğunu. Olayların kaybolduğu ya da tekrarlandığı yer tam da bu boşluktur.
Alımı işlemeden ayıran bir desene ihtiyacınız vardır. Alım hızlı ve savunmacıdır; işleme ise kasıtlı ve denetlenebilirdir. Bu 2 aşamayı tek adım olarak ele almak, webhook güvenilirlik sorunlarının temel nedenidir.
- Alım: isteği kabul edin, hızlı bir onay döndürün, üretim durumuna hiçbir şey yazmayın.
- İşleme: doğrulayın, normalleştirin, yönlendirin ve denetlenebilir bir sırayla kaydedin.
Bu aşamaları birbirinden ayırmak, olayları yeniden oynatmanıza, hataları incelemenize ve satıcıyla yeniden müzakere etmeksizin akış sonrası mantığı değiştirmenize olanak tanır.
Adım 1 — Her şeyden önce göndereni doğrulayın
İlk soru "bu olay ne söylüyor?" değil, "bu olay gerçekten satıcıdan mı geldi?" olmalıdır. Satıcılar genellikle webhook yüklerini paylaşılan bir gizli anahtar ya da açık anahtar şemasıyla imzalar. Uç noktanız, iş verisi için gövdeyi okumadan önce bu imzayı doğrulamalıdır.
İmza yoksa veya geçersizse hata döndürün ve durdurun. Başarısız bir doğrulama değerli bir bilgidir — zaman damgasını, kaynak IP'yi ve hata nedenini kaydedin, ardından devam edin.
Pratik bir ayrıntı: imzayı, gövdenin ayrıştırılmış ya da yeniden serileştirilmiş hali üzerinden değil, aldığınız ham baytlar üzerinden hesaplayın. Ayrıştırma, yük geçerli olsa bile boşlukları veya anahtar sıralamasını sessizce değiştirebilir ve karşılaştırmayı bozabilir.
İkinci bir pratik ayrıntı: imzalama gizli anahtarınıza bir kimlik bilgisi gibi davranın. Belirli aralıklarla döndürün, uygulama kodunuzun dışında saklayın ve alım katmanınızın döndürme sırasında hem eski hem yeni anahtarın kısa bir süre birlikte geçerli olduğu bir örtüşme penceresini kabul edebildiğinden emin olun.
Adım 2 — Ham olayı hemen kaydedin
İmza doğrulandıktan sonra, başka herhangi bir işlem yapmadan önce değiştirilmemiş yükü kalıcı bir depoya yazın. Bu kayıt hem denetim günlüğünüz hem de yeniden oynatma kaynağınızdır. Bir akış sonrası sistem yarın başarısız olursa ya da satıcı daha önceki bir olayı çelişen düzeltilmiş bir olayla gönderirse, orijinal baytların elinizin altında olmasını istersiniz.
En az şu alanları kaydedin:
| Alan | Amaç |
|---|---|
| Alım zaman damgası | Olay sırasını satıcı saatinden bağımsız olarak belirler |
| Satıcı olay kimliği | Yeniden oynatmada idempotensi kontrollerine olanak tanır |
| Ham gövde | Yeniden işleme için gerçeğin kaynağı |
| İmza başlığı | Anahtarınız döndürüldüğünde sonradan yeniden doğrulamaya izin verir |
| Döndürülen HTTP durumu | Onayı doğru şekilde ilettiğinizi teyit eder |
| Ulaşılan alım aşaması | Herhangi bir hatadan önce işlemenin ne kadar ilerlediğini gösterir |
İş mantığına ulaşmak için acele ettiğinizde bu adımı atlamayın. Ham kaydı yazmak ucuzdur; sonradan yeniden oluşturmak pahalıdır.
Adım 3 — Yükü kendi şemanıza normalleştirin
Satıcılar yük yapılarını değiştirir. Dize olan bir alan diziye dönüşür; sayısal olan bir durum kodu dize değişmezine dönüşür. İç sistemleriniz bu değişiklikleri doğrudan absorbe etmemelidir. Normalleştirme, onları koruyan çeviri katmanıdır.
Satıcının yapısını kendi kurallı olay şemanıza dönüştüren ince bir eşleme işlevi yazın. Bu işlevi sürümlü ve test edilmiş tutun. Satıcı bir şema değişikliği duyurduğunda, veriye dokunan her tüketiciye bakarak değil, yalnızca normalleştiriciyi güncelleyerek tek bir yerde değişiklik yaparsınız.
Satıcı yükünde bir alan eksik veya belirsizse, sessizce varsayılan değer atamak yerine bunu normalleştirilmiş çıktınızda açıkça belirtin. Bir işaretle birlikte gelen null, gerçek görünen uydurulmuş bir değerden daha kullanışlıdır.
Normalleştirme hatalarını ayrı bir olay durumu olarak izleyin. Doğrulamayı geçen ancak normalleştirmede başarısız olan bir olay size belirli bir şey söyler: satıcının yapısı değişmiş ya da eşlemenizde bir boşluk var. Bu ayrım, gece 2'de bir kuyruğu incelerken önem taşır.
Adım 4 — Olayı tam olarak bir kez yönlendirin
Normalleştirmenin ardından olayın doğru iç sisteme — CRM'inize, faturalama motorunuza, sağlama hizmetinize — ulaşması gerekir. Yönlendirme adımı belirleyici olmalıdır: bu olay türü ve bu normalleştirilmiş yapı için tek bir tanımlı hedef vardır.
İdempotensi burada önem taşır. Satıcılar zamanında onay alamadıklarında teslimatı yeniden dener. Yönlendirme mantığınız, satıcı olay kimliğini Adım 2'de yazdığınız kayıtlarla karşılaştırmalıdır. Olay zaten yönlendirildiyse, tekrarlananı onaylayın ve durdurun.
Mimariniz bunu açıkça gerektirmedikçe bu aşamada yayılmadan kaçının. Önce tek bir sahibe yönlendirmek ve o sahibin akış sonrasında neleri bildireceğine karar vermesine izin vermek, hesap verebilirliği açık tutar.
Basit bir olay durumu modeli
Bu desene yapılabilecek en pratik eklemelerden biri, her olayın geçtiği küçük bir durum makinesidir. Ekibinize ortak bir söz dağarcığı kazandırır ve hata kuyruğunuzu anlamsız yerine anlamlı kılar.
Asgari durum kümesi:
- received — istek ulaştı ve onaylandı.
- verified — imza kontrolü geçti.
- verification_failed — imza kontrolü başarısız oldu; daha fazla işlem yapılmayacak.
- recorded — ham yük kalıcı depolamaya alındı.
- normalized — yük kurallı şemanıza eşlendi.
- normalization_failed — eşleme hata verdi; inceleme için bekletildi.
- routed — normalleştirilmiş olay sahibine iletildi.
- duplicate — satıcı olay kimliği zaten yönlendirilmişti; onaylandı ve atıldı.
- stalled — yönlendirme denendi ancak hedef olayı kabul etmedi.
Her durum geçişi bir kayıt yazar. Takılı kalan bir olayı açtığınızda tam olarak nerede ve neden durduğunu görebilirsiniz. Bu görünürlük, 10 dakikalık bir düzeltme ile 2 saatlik bir araştırma arasındaki farktır.
Üretime hazırlık kontrol listesi
Yeni bir satıcı webhook entegrasyonunu canlıya almadan önce şu maddeleri gözden geçirin:
- İmza doğrulaması zorunludur — her gelen istek için isteğe bağlı değil.
- Ham depolamanın kalıcı olduğu doğrulanmıştır — yeniden başlatma veya dağıtım işlenmemiş olayları kaybettirmez.
- İdempotensi test edilmiştir — aynı olay kimliği iki kez oynatılarak ikinci geçişin yan etki üretmediği doğrulanmıştır.
- Normalleştirme hataları inceleme kuyruğuna yönlendirilir, sessizce atılmaz.
- Saklama süreleri yazılı olarak tanımlanmıştır — hem ham hem normalleştirilmiş olaylar için.
- Bir yeniden oynatma prosedürü mevcuttur ve en az bir ekip üyesi bunu üretim dışı bir ortamda çalıştırmıştır.
- Sahiplik belgelenmiştir — her olay türü adlandırılmış bir ekip veya role eşlenmiştir.
- Uyarılar yapılandırılmıştır — yalnızca tam kesintiler için değil, büyüyen bir hata kuyruğu için de.
Bu liste kapsamlı değildir, ancak bu 8 maddeyi karşılamak sessiz veri kaybının en yaygın nedenlerini ortadan kaldırır.
Bu desen için Apivom Atlas kullanımı
Apivom Atlas, satıcı sistemleri ile iç uygulamalarınız arasında konumlanmak üzere tasarlanmış bir API entegrasyon ağ geçididir. Bir ağ geçidi olarak Apivom Atlas, yukarıda açıklanan alım sırasını — bu mantığı satıcı verilerini tüketen her uygulamaya gömmeden — uygulayabileceğiniz yönetilen bir katman sunar.
Birden fazla satıcıyla bağlantıları yöneten entegrasyon sahipleri için tek bir ağ geçidi katmanına sahip olmak, alım davranışındaki değişikliklerin — örneğin bir normalleştirme kuralını güncellemek veya imzalama gizli anahtarını döndürmek — tek bir yerde yapılabileceği anlamına gelir. Bu merkezileştirme, yığınınızın farklı bölümlerinde tutarsız işleme riskini azaltır.
Apivom Atlas, yazılım kanalı için inşa edilmiştir; bu da onu bayilerin, VAR'ların ve distribütörlerin her gün çalıştığı satıcı ilişkileri etrafında şekillendirir.
Yetersiz kaldığı durumlar
Webhook alımı, kapsamı dışında kalan 2 şeyi düzeltemez — ister deseni kendiniz oluşturun ister Apivom Atlas kullanın.
Birincisi, eksik satıcı yükleri. Satıcı, iş mantığınızın gerektirdiği bir alanı çıkarırsa hiçbir alım deseni onu icat edemez. Eksik veriyi almak için satıcı API'sine geri çağrı yapmanız ya da bazı olayların manuel inceleme gerektireceğini kabul etmeniz gerekir. Normalleştirme adımı boşluğu görünür kılar; doldurmaz.
İkincisi, belirsiz iş sahipliği. Alım deseni olayları tanımlı bir hedefe yönlendirir. Kuruluşunuz belirli bir olay türüne hangi ekibin sahip olduğu konusunda anlaşmamışsa, olay bir uç noktaya ulaşır ve orada takılır. Durum modeli sahiplik boşluğunu gün yüzüne çıkarır; çözmez. Bu konuşmanın ilk üretim olayından sonra değil, canlıya geçmeden önce yapılması gerekir.
Kurtarmaya yetecek kanıtı korumak
Webhook alımında güvenilirlik büyük ölçüde kanıtla ilgilidir. Bir şey başarısız olduğunda şu soruları yanıtlamanız gerekir: olayı aldık mı, doğruladık mı, doğru normalleştirdik mi ve doğru yere yönlendirdik mi? Yukarıdaki desendeki her adım bu sorulardan birini yanıtlayan bir kayıt üretir.
Saklama politikası önem taşır. Ham olayları satıcının yeniden deneme penceresini ve kendi araştırma pencerenizi kapsayacak kadar uzun süre saklayın. Normalleştirilmiş olayları müşterilerinizden veya finans ekibinizden gelen denetim taleplerine yanıt verebilecek kadar uzun süre saklayın. Bu süreleri açıkça tanımlayın — "yeterince uzun" bir politika değildir.
Hata kuyruğunuzu yalnızca bir şey bozulduğunda değil, belirli bir programa göre gözden geçirin. Az sayıda takılı olay normaldir; büyüyen bir kuyruk, satıcı şemasının değiştiğinin veya akış sonrası bir sistemin bozulduğunun sinyalidir. Yukarıda açıklanan olay durumu modeli, ham yükleri ayrıştırmak yerine durumları okuduğunuz için bu incelemeyi hızlı kılar.
Apivom Atlas'ın bu deseni nasıl ele aldığını görmek için https://apivom.com/products/atlas adresini ziyaret edebilirsiniz.