15 Ara 2024·6 dk okuma

Güvenli fatura güncellemeleri için idempotent ödeme webhook'ları kontrol listesi

Tekrarlayan olayları ayıklama, yeniden denemeleri yönetme ve faturalar, abonelikler ile yetkilendirmeleri güvenle güncelleme için idempotent ödeme webhook'ları kontrol listesi.

Güvenli fatura güncellemeleri için idempotent ödeme webhook'ları kontrol listesi

Ödeme webhook'ları neden çift güncellemelere yol açar\n\nBir ödeme webhook'u, ödeme sağlayıcınızın arka ucunuza bir şey önemli olduğunda gönderdiği mesaja benzer: bir tahsilat başarılı oldu, bir fatura ödendi, bir abonelik yenilendi veya bir iade yapıldı. Sağlayıcı temelde “Olan bu, kayıtlarınızı güncelleyin” der.\n\nÇiftler, webhook teslimatı güvenilir olacak şekilde tasarlandığı için ve “tam olarak bir kez” garanti edilmediği için oluşur. Sunucunuz yavaşsa, zaman aşımına uğruyorsa, hata döndürüyorsa veya kısa süreliğine kullanılamıyorsa, sağlayıcı genellikle aynı olayı yeniden dener. Ayrıca aynı gerçek dünyadaki işlemi işaret eden iki farklı olay görebilirsiniz (örneğin, bir ödemeyle ilişkili hem bir invoice olayı hem de bir payment olayı). Olaylar ayrıca özellikle iadelere benzer hızlı takiplerde sıralama dışı gelebilir.\n\nHandler'ınız idempotent değilse, aynı olayı iki kez uygulayabilir ve müşterilerin ve finans ekiplerinin hemen fark edeceği sorunlar ortaya çıkar:\n\n- Bir faturanın iki kez "ödendi" olarak işaretlenmesi, yinelenen muhasebe kayıtları oluşturur\n- Bir yenilemenin iki kez uygulanması, erişimi gereğinden fazla uzatır\n- Yetkilendirmelerin iki kez verilmesi (fazladan kredi, koltuk veya özellik)\n- İadeler veya chargeback'lerin erişimi doğru şekilde geri almaması\n\nBu sadece “iyi uygulama” değil. Güvenilir hissi veren faturalama ile destek talebi yaratan faturalama arasındaki farktır.\n\nBu kontrol listesinin hedefi basit: gelen her olayı “en fazla bir kez uygula” olarak ele almak. Her olay için kalıcı bir kimlik saklayacaksınız, yeniden denemeleri güvenli şekilde yöneteceksiniz ve faturaları, abonelikleri ve yetkilendirmeleri kontrollü bir şekilde güncelleyeceksiniz. AppMaster gibi no-code bir araçla arka uç inşa ediyorsanız aynı kurallar geçerlidir: net bir veri modeli ve yeniden denemeler altında doğru kalan tekrar edilebilir bir handler akışına ihtiyacınız var.\n\n## Webhook'lara uygulayabileceğiniz idempotentlik temelleri\n\nIdempotentlik, aynı girdiyi birden çok işlediğinizde aynı nihai durumu elde etmenizdir. Faturalama açısından: bir fatura bir kez ödenmiş olur, bir abonelik bir kez güncellenir ve erişim bir kez verilir; webhook birden çok teslim edilse bile.\n\nSağlayıcılar, endpoint'iniz zaman aşımına uğradığında, 5xx döndüğünde veya ağ kopmaları olduğunda yeniden dener. Bu yeniden denemeler aynı olayı tekrarlar. Bu, günler sonra oluşan gerçek bir değişikliği temsil eden ayrı bir olaydan (örneğin bir iade) farklıdır. Yeni olayların farklı ID'leri olur.\n\nBunu çalıştırmak için iki şeye ihtiyacınız var: stabil kimlikler ve zaten gördüklerinize dair küçük bir “hafıza”.\n\n### Hangi ID'ler önemli (ve ne saklamalısınız)\n\nÇoğu ödeme platformu, webhook olayı için benzersiz bir event ID içerir. Bazıları ayrıca bir request ID, idempotency key veya yük içinde benzersiz bir ödeme nesnesi ID'si (örneğin charge veya payment intent) sağlar.\n\nSaklayın ki şu soruyu cevaplayabilesiniz: “Bu tam olarak aynı olayı daha önce uyguladım mı?”\n\nPratik bir minimum:\n\n- Olay ID'si (benzersiz anahtar)\n- Olay türü (hata ayıklama için faydalı)\n- Alınma zaman damgası\n- İşleme durumu (processed/failed gibi)\n- Etkilenen müşteri, fatura veya aboneliğe referans\n\nAna hamle, olay ID'sini benzersiz bir kısıtlama (unique constraint) ile bir tabloda saklamaktır. Ardından handler'ınız güvenle şu adımı yapabilir: önce event ID'yi insert edin; zaten varsa durun ve 200 döndürün.\n\n### Dedupe kayıtlarını ne kadar süre saklamalısınız\n\nGeç gelen yeniden denemeleri ve destek soruşturmalarını kapsayacak kadar saklayın. Yaygın bir pencere 30 ila 90 gündür. Chargeback, itiraz veya daha uzun abonelik döngüleriyle uğraşıyorsanız, daha uzun (6–12 ay) tutun ve tablo hızlı kalması için eski satırları temizleyin.\n\nAppMaster gibi üretilmiş bir arka uçta, bu temiz bir şekilde WebhookEvents modeli olarak eşleşir; event ID üzerinde benzersiz bir alan ve kopya tespit edildiğinde erken çıkış yapan bir Business Process oluşturun.\n\n## Olayları çoğaltmayı önlemek için basit bir veri modeli tasarlayın\n\nİyi bir webhook handler'ı çoğunlukla bir veri problemidir. Her sağlayıcı olayını tam olarak bir kez kaydedebiliyorsanız, ardından gelen her şey daha güvenli olur.\n\nBir makbuz günlüğü gibi davranan tek bir tabloyla başlayın. PostgreSQL'de (ve AppMaster’ın Data Designer'ında modellendiğinde) bunu küçük ve katı tutun ki çoğaltmalar hızlıca başarısız olsun.\n\n### Gerekli minimum\n\nwebhook_events tablosu için pratik bir temel şunlardır:\n\n- provider (text, ör. stripe)\n- provider_event_id (text, zorunlu)\n- status (text, ör. received, processed, failed)\n- processed_at (timestamp, nullable)\n- raw_payload (jsonb veya text)\n\n(provider, provider_event_id) üzerinde benzersiz bir kısıtlama ekleyin. Bu tek kural sizin ana dedupe savunma hattınızdır.\n\nAyrıca güncelleme yapmak için kullandığınız iş ID'lerini saklamak istersiniz. Bunlar webhook olay ID'sinden farklıdır.\n\nYaygın örnekler customer_id, invoice_id ve subscription_id içerir. Sağlayıcılar genellikle sayısal olmayan ID'ler kullandığı için bunları text olarak tutun.\n\n### Ham payload vs ayrıştırılmış alanlar\n\nHata ayıklama ve daha sonra yeniden işlem için ham payload'u saklayın. Ayrıştırılmış alanlar sorgulamayı ve raporlamayı kolaylaştırır, fakat sadece gerçekten kullandığınız alanları saklayın.\n\nBasit bir yaklaşım:\n\n- Her zaman raw_payload saklayın\n- Ayrıca sık sorguladığınız birkaç ayrıştırılmış ID'yi (customer, invoice, subscription) saklayın\n- Filtreleme için normalleştirilmiş bir event_type (text) saklayın\n\nBir invoice.paid olayı iki kez gelirse, benzersiz kısıtlama ikinci insert'i engeller. Yine de denetimler için ham payload elinizde olur ve ayrıştırılmış invoice ID, ilk seferde güncellediğiniz fatura kaydını kolayca bulmanızı sağlar.\n\n## Adım adım: güvenli bir webhook handler akışı\n\nGüvenli bir handler kasıtlı olarak sıkıcıdır. Sağlayıcı aynı olayı yeniden denese veya olayları sıralama dışı gönderse bile her seferinde aynı şekilde davranır.\n\n### Her seferinde izlenecek 5 adımlık akış\n\n1) İmza doğrulamasını yapın ve payload'u ayrıştırın. İmza kontrollerinden geçen, beklenmeyen bir olay türü olmayan veya ayrıştırılamayan istekleri reddedin.\n\n2) Faturalama verilerine dokunmadan önce olay kaydını yazın. Sağlayıcı olay ID'sini, türünü, oluşturulma zamanını ve ham payload'u (veya bir hash) kaydedin. Olay ID zaten varsa, bunu bir kopya olarak ele alın ve durun.\n\n3) Olayı tek bir “sahip” kayda eşleyin. Ne güncellediğinize karar verin: fatura mı, abonelik mi, müşteri mi. Dış ID'leri kayıtlarınıza saklayın ki doğrudan arayabilesiniz.\n\n4) Güvenli bir durum değişikliği uygulayın. Yalnızca durumu ileri taşıyın. Geç gelen bir invoice.updated nedeniyle ödenmiş bir faturayı geri almayın. Uyguladığınız şeyi (eski durum, yeni durum, zaman damgası, olay ID) denetim için kaydedin.\n\n5) Hızlı yanıt verin ve sonucu kaydedin. Olay güvenle saklandıktan ve işlenmiş veya yok sayılmışsa başarı döndürün. İşlenip işlenmediğini, deduplandığını veya reddedildiğini ve nedenini loglayın.\n\nAppMaster'da bu genellikle webhook olayları için bir veritabanı tablosu ve ardından “görüldü mü?” kontrolü yapan bir Business Process olarak ortaya çıkar; sonra minimum güncelleme adımları çalıştırılır.\n\n## Yeniden denemeleri, zaman aşımını ve sıralama dışı teslimatı ele alma\n\nSağlayıcılar webhook'ları, hızlı bir başarı yanıtı almadıklarında yeniden gönderir. Ayrıca olayları sıralama dışı gönderebilirler. Handler'ınız aynı güncellemenin iki kez gelmesine veya daha sonraki bir güncellemenin önce gelmesine karşı güvenli kalmalıdır.\n\nPratik bir kural: hızlı cevap verin, işi sonra yapın. Webhook isteğini bir makbuz olarak ele alın, ağır mantığı çalıştırmak için bir yer olarak değil. Eğer üçüncü taraf API'ler çağırıyor, PDF üretiyor veya istek içinde hesaplamalar yapıyorsanız zaman aşımını artırır ve daha fazla yeniden denemeye neden olursunuz.\n\n### Sıralama dışı: en yeni gerçeği koruyun\n\nSıralama dışı teslimat normaldir. Her değişikliği uygulamadan önce iki kontrol kullanın:\n\n- Zaman damgalarını karşılaştırın: bir nesne (fatura, abonelik, yetki) için zaten sakladığınızdan daha yeni bir olaysa uygulayın.\n- Zaman damgalarının yakın veya belirsiz olduğu durumlarda durum önceliği kullanın: paid, open'dan; canceled, active'den üstün olsun.\n\nZaten bir faturayı ödendi olarak kaydettiyseniz ve geç bir “open” olayı gelirse, onu yoksayın. “Canceled” aldıysanız ve daha sonra daha eski bir “active” güncellemesi gelirse iptal edilmiş olanı tutun.\n\n### Yoksayma vs kuyruğa alma\n\nBir olayı modasının geçtiğini veya zaten uygulandığını kanıtlayabiliyorsanız yoksayın. Bir olayı, müşteri kaydı daha sonra geldiği için gerekli verilere bağlı olduğunda kuyruğa alın.\n\nPratik bir desen:\n\n- Olayı hemen işleme durumuyla saklayın (received, processing, done, failed)\n- Bağımlılıklar eksikse, beklemede olarak işaretleyin ve arka planda yeniden deneyin\n- Yeniden deneme limiti koyun ve tekrarlayan başarısızlıklarda alarm üretin\n\nAppMaster'da bu, webhook olayları tablosu ile iyi eşleşir ve Business Process isteği hızla onaylayıp kuyruğa alınmış olayları asenkron olarak işler.\n\n## Faturalar, abonelikler ve yetkilendirmeleri güvenle güncelleme\n\nÇoğaltmayı hallettikten sonra bir sonraki risk bölünmüş fatura durumudur: fatura "ödendi" diyor ama abonelik hala gecikmiş, ya da erişim iki kez verildi ve hiç geri alınmadı. Her webhook'u bir durum geçişi olarak ele alın ve bunu tek bir atomik güncelleme ile uygulayın.\n\n### Faturalar: durum değişikliklerini monoton yapın\n\nFaturalar paid, voided ve refunded gibi durumlar arasında geçiş yapabilir. Ayrıca kısmi ödemeler de olabilir. Bir faturayı hangi olayın geldiğine bakarak rastgele toggle yapmayın. Geçerli durumu ve önemli tutarları saklayın (amount_paid, amount_refunded) ve yalnızca ileri güvenli geçişlere izin verin.\n\nPratik kurallar:\n\n- Bir faturayı sadece ilk kez paid olarak işaretleyin\n- İadeler için amount_refunded değerini fatura toplamına kadar artırın; asla azaltmayın\n- Bir fatura voided olursa, yerine getirme aksiyonlarını durdurun ancak kaydı denetim için saklayın\n- Kısmi ödemeler için, “tamamen ödendi” avantajları vermeden tutarları güncelleyin\n\n### Abonelikler ve yetkilendirmeler: bir kez ver, bir kez geri al\n\nAbonelikler yenileme, iptal ve grace dönemleri içerir. Abonelik durumu ve dönem sınırlarını (current_period_start/end) saklayın, ardından yetkilendirme pencerelerini bu verilerden türetin. Yetkilendirmeler tek bir boolean değil, açık kayıtlar olmalıdır.\n\nErişim kontrolü için:\n\n- Her kullanıcı/ürün/dönem için bir yetkilendirme verme\n- Erişim sona erdiğinde bir iptal kaydı oluşturma (iptal, iade, chargeback)\n- Her değişikliğin hangi webhook olayı tarafından yapıldığını gösteren denetim izi\n\n### Bölünmüş durumları önlemek için bir transaction kullanın\n\nFatura, abonelik ve yetkilendirme güncellemelerini tek bir veritabanı işlemi içinde uygulayın. Geçerli satırları okuyun, bu olayın zaten uygulanıp uygulanmadığını kontrol edin, sonra tüm değişiklikleri birlikte yazın. Bir şey başarısız olursa geri alın ki “fatura ödendi ama erişim yok” veya tersi durumu yaşamayın.\n\nAppMaster'da bu genellikle PostgreSQL'i tek kontrollü bir yol içinde güncelleyen ve iş değişikliğiyle birlikte denetim girdisi yazan bir Business Process akışına karşılık gelir.\n\n## Webhook uç noktaları için güvenlik ve veri güvenliği kontrolleri\n\nWebhook güvenliği doğruluğun bir parçasıdır. Bir saldırgan uç noktanıza erişebiliyorsa, sahte “ödendi” durumları oluşturmaya çalışabilir. Deduplikasyon olsa bile, olayın gerçek olduğunu kanıtlamalı ve müşteri verilerini korumalısınız.\n\n### Faturalama verilerine dokunmadan önce göndereni doğrulayın\n\nHer istekte imzayı doğrulayın. Stripe için bu genellikle Stripe-Signature başlığını kontrol etmek, ham istek gövdesini (yeniden yazılmamış JSON değil) kullanmak ve eski bir zaman damgası olan olayları reddetmeyi içerir. Eksik başlıkları kesin bir hata olarak ele alın.\n\nTemel doğrulamaları erken yapın: doğru HTTP metodu, Content-Type ve gerekli alanlar (event id, type ve fatura veya abonelik bulmak için kullanacağınız nesne id). AppMaster'da bunu oluşturuyorsanız imza gizlilerini ortam değişkenlerinde veya güvenli konfigürasyonda saklayın; veritabanında veya istemci kodunda tutmayın.\n\nKısa bir güvenlik kontrol listesi:\n\n- Geçerli imza ve taze zaman damgası olmayan istekleri reddedin\n- Beklenen başlıkları ve içerik tipini zorunlu kılın\n- Webhook handler için en az ayrıcalıklı veritabanı erişimi kullanın\n- Gizli anahtarları tablolarınız dışında saklayın (env/config) ve gerektiğinde döndürün\n- Olay güvenle saklandıktan sonra yalnızca 2xx döndürün\n\n### Gizli verileri sızdırmadan kullanılabilir loglar tutun\n\nYeniden denemeleri ve itirazları hata ayıklamak için yeterli log tutun, ancak hassas değerleri sızdırmaktan kaçının. Güvenli bir PII alt kümesi saklayın: sağlayıcı müşteri ID'si, dahili kullanıcı ID'si ve belki maskelenmiş bir e-posta (a***@domain.com). Tam kart verilerini, tam adresleri veya ham yetkilendirme başlıklarını asla saklamayın.\n\nOlanları yeniden oluşturmanıza yardımcı olacak şeyleri loglayın:\n\n- Sağlayıcı olay id'si, türü, oluşturulma zamanı\n- Doğrulama sonucu (imza ok/failed) ama imzayı saklamadan\n- Dedupe kararı (yeni vs zaten işlenmiş)\n- Dokunulan dahili kayıt ID'leri (invoice/subscription/entitlement)\n- Hata nedeni ve yeniden deneme sayısı (kuyruğa alıyorsanız)\n\nTemel istismara karşı koruma ekleyin: IP başına rate limit koyun ve (mümkünse) müşteri ID bazında da limit uygulayın; eğer kurulumunuz destekliyorsa sadece bilinen sağlayıcı IP aralıklarını kabul etmeyi düşünün.\n\n## Çift ücretlendirme veya çift erişime yol açan yaygın hatalar\n\nÇoğu faturalama hatası matematikle ilgili değildir. Bir webhook teslimatını tek, güvenilir bir mesaj gibi ele aldığınızda olur.\n\nEn sık çoğaltılmış güncellemelere yol açan hatalar:\n\n- Zaman damgası veya tutar ile dedupe yapmak, event ID yerine. Farklı olaylar aynı tutara sahip olabilir ve yeniden denemeler dakikalar sonra gelebilir. Sağlayıcının benzersiz event ID'sini kullanın.\n- İmzayı doğrulamadan önce veritabanını güncellemek. Önce doğrulayın, sonra ayrıştırın, sonra işlem yapın.\n- Her olayı, mevcut durumu kontrol etmeden kaynağı olarak kabul etmek. Bir faturayı zaten ödendi, iade edilmiş veya void ise körü körüne paid yapmayın.\n- Aynı satın alma için birden fazla yetkilendirme oluşturmaya izin vermek. Yeniden denemeler yinelenen satırlar yaratabilir. “subscription_id için yetki olduğundan emin ol” gibi bir upsert tercih edin, sonra tarihleri/limitleri güncelleyin.\n\n- Bir bildirim servisi çalışmadığı için webhook'u başarısızlığa uğratmak. E-posta, SMS, Slack veya Telegram faturalamayı engellememeli. Bildirimleri kuyruğa alın ve temel faturalama değişiklikleri güvenle saklandıktan sonra yine de başarı dönün.\n\nBasit bir örnek: bir yenileme olayı iki kez gelir. İlk teslimat bir yetki satırı oluşturur. Yeniden deneme ikinci bir satır oluşturur ve uygulamanız “iki aktif yetki” görür ve ekstra koltuk veya kredi verir.\n\nAppMaster'da çözüm çoğunlukla akışla ilgilidir: önce doğrula, benzersiz kısıtlaması olan olay kaydını insert et, durum kontrolleri ile faturalama güncellemelerini uygula ve yan etkileri (e-postalar, makbuzlar) yeniden denemelere yol açmayacak asenkron adımlara gönder.\n\n## Gerçekçi örnek: yinelenen yenileme + sonraki iade\n\nBu desen korkutucu görünebilir, ama handler'ınız tekrar çalıştırılmaya elverişli ise yönetilebilir.\n\nBir müşteri aylık planda. Stripe bir yenileme olayı (invoice.paid gibi) gönderir. Sunucunuz bunu alır, veritabanını günceller ama 200 döndürmek için çok uzun sürer (cold start, yoğun veritabanı). Stripe bunun başarısız olduğunu varsayar ve aynı olayı yeniden dener.\n\nİlk teslimatta erişim verirsiniz. Yeniden denemede aynı olay olduğunu tespit eder ve hiçbir şey yapmazsınız. Daha sonra bir iade olayı (charge.refunded gibi) gelir ve erişimi bir kez geri alırsınız.\n\nVeritabanınızda durumu modellemenin basit bir yolu (AppMaster Data Designer'da oluşturulabilecek tablolar):\n\n- webhook_events(event_id UNIQUE, type, processed_at, status)\n- invoices(invoice_id UNIQUE, subscription_id, status, paid_at, refunded_at)\n- entitlements(customer_id, product, active, valid_until, source_invoice_id)\n\n### Her olaydan sonra veritabanında ne olmalı\n\nOlay A (yenileme, ilk teslimat) sonrası: webhook_events içinde event_id=evt_123 için status=processed olan yeni bir satır. invoices paid olarak işaretlenmiş. entitlements.active=true ve valid_until bir faturalama dönemi ileriye taşınmış.\n\nOlay A tekrarlandığında (yenileme, retry): webhook_events insert'i (benzersiz event_id) başarısız olur veya handler zaten işlenmiş görür. Faturalar veya yetkilendirmelerde değişiklik olmaz.\n\nOlay B (iade): webhook_events için event_id=evt_456 ile yeni bir satır. invoices.refunded_at set edilir ve status=refunded olur. entitlements.active=false ya da valid_until şu an olarak güncellenir; source_invoice_id kullanılarak doğru erişim bir kez geri alınır.\n\nÖnemli detay: dedupe kontrolü herhangi bir verme veya geri alma yazmadan önce yapılır.\n\n## Lansman öncesi hızlı kontrol listesi\n\nCanlı webhook'ları açmadan önce, gerçek bir olayın sağlayıcı tarafından iki kez (veya on kez) gönderilse bile faturalama kayıtlarını tam olarak bir kez güncellediğine dair kanıta ihtiyacınız vardır.\n\nKurulumunuzu uçtan uca doğrulamak için bu kontrol listesini kullanın:\n\n- Gelen her olayı önce kaydettiğinizi doğrulayın (ham payload, event id, type, oluşturulma zamanı ve imza doğrulama sonucu), sonraki adımlar başarısız olsa bile.\n- Aynı sağlayıcı event id'si ile çoğaltmaların erken tespit edildiğini ve handler'ın faturaları, abonelikleri veya yetkilendirmeleri değiştirmeden çıktığını doğrulayın.\n\n- İş güncellemesinin tek seferlik olduğunu kanıtlayın: bir fatura durum değişikliği, bir abonelik durumu değişikliği, bir yetkilendirme verme veya geri alma yalnızca bir kez gerçekleşmeli.\n\n- Hataların güvenli bir şekilde yeniden oynatılabilmesi için yeterli ayrıntıyla kaydedildiğinden emin olun (hata mesajı, başarısız olan adım, yeniden deneme durumu).\n\n- Handler'ınızın hızlı yanıt verdiğini test edin: kaydı aldıktan sonra onaylayın ve isteğin içinde yavaş işleri yapmaktan kaçının.\n\nBüyük bir izleme kurulumu gerekmez ama sinyallere ihtiyacınız var. Loglar veya basit panolar üzerinden şunları takip edin:\n\n- Çoğaltılmış teslimatlarda ani artışlar (genellikle normal, ama büyük sıçramalar zaman aşımı veya sağlayıcı sorununu işaret edebilir)\n- Olay türüne göre yüksek hata oranı (ör. invoice payment failed)\n- Yeniden denemede sıkışmış olayların büyüyen yığınağı\n- Tutarsızlık kontrolleri (ödeli fatura ama eksik yetkilendirme, iptal edilmiş abonelik ama hala aktif erişim)\n- İşleme süresinde ani artışlar\n\nAppMaster kullanıyorsanız, event depolamayı Data Designer içinde adanmış bir tabloda tutun ve “işlendi olarak işaretle” kararını Business Process içinde tek, atomik bir karar noktası yapın.\n\n## Sonraki adımlar: test edin, izleyin ve no-code arka uçta inşa edin\n\nTest etmek idempotentliğin kendini kanıtladığı yerdir. Sadece mutlu yolu çalıştırmayın. Aynı olayı birkaç kez yeniden oynatın, olayları sıralama dışı gönderin ve sağlayıcınızın yeniden denemelerine yol açmak için zaman aşımı zorlayın. İkinci, üçüncü ve onuncu teslimat hiçbir şeyi değiştirmemeli.\n\nErken dönemde backfilling planlayın. Er ya da geç bir hata düzeltmesi, şema değişikliği veya sağlayıcı sorunu sonrası geçmiş olayları yeniden işlemeyi isteyeceksiniz. Handler'ınız gerçekten idempotent ise backfilling, çoğaltma yaratmadan “aynı pipeline üzerinden olayları yeniden oynatma” olur.\n\nDestek ekibinin tahmin yürütmesine gerek kalmaması için küçük bir çalışma kılavuzu da hazırlayın:\n\n- Olay ID'sini bulun ve işlenmiş olarak kayıtlı olup olmadığını kontrol edin\n- Fatura veya abonelik kaydını kontrol edip beklenen durum ve zaman damgalarını doğrulayın\n- Yetkilendirme kaydını inceleyin (hangi erişim verildi, ne zaman ve neden)\n- Gerekirse tek bir olay ID'si için güvenli bir yeniden işleme modu ile işlemeyi yeniden çalıştırın\n- Veri tutarsızsa tek bir düzeltici işlem uygulayın ve bunu kaydedin\n\nÇok fazla boilerplate yazmak istemiyorsanız, AppMaster (appmaster.io) çekirdek tabloları modellemenize ve webhook akışını görsel bir Business Process ile oluşturmanıza olanak verir; aynı zamanda arka uç için gerçek kaynak kodu üretir.\n\nCanlı trafiği ve geliri ölçeklemeden önce no-code üretilmiş bir arka uçta webhook handler'ınızı uçtan uca inşa edin ve yeniden denemeler altında güvenli kaldığından emin olun.

SSS

Why does my payment provider send the same webhook more than once?

Tekrarlayan webhook iletileri normaldir çünkü sağlayıcılar en az bir kez teslimi garanti edecek şekilde çalışır. Uç noktanız zaman aşımına uğrarsa, 5xx dönerse veya bağlantı kısa süreliğine koparsa, sağlayıcı aynı olayı başarılı bir yanıt alana kadar tekrar gönderir.

What’s the best way to dedupe webhook events?

Sağlayıcının benzersiz olay kimliğini (event ID) kullanın; tutar, zaman damgası veya müşteri e-postası değil. Olay kimliğini bir unique constraint ile saklayın, böylece bir yeniden deneme hemen tespit edilip güvenli şekilde görmezden gelinebilir.

Should I save the event before updating billing records?

Olay kaydını faturaları, abonelikleri veya yetkilendirmeleri güncellemeden önce ekleyin. Eğer insert, olay kimliği zaten varsa başarısız olursa işlemi durdurun ve başarı döndürün; böylece yeniden denemeler çift güncelleme oluşturmaz.

How long should I keep webhook dedupe records?

Gecikmiş yeniden denemeleri ve soruşturmaları kapsayacak kadar saklayın. Pratik bir varsayılan aralık 30–90 gündir; itirazlar, chargeback veya uzun abonelik döngüleri için daha uzun (6–12 ay) tutun ve tablonun hızlı kalması için eski satırları silin.

Do I really need signature verification if I already dedupe events?

İmzayı doğrulamadan önce fatura verilerine dokunmayın; sonra ayrıştırma ve gerekli alan doğrulamasını yapın. Eğer imza doğrulaması başarısız olursa isteği reddedin ve faturalama değişiklikleri yazmayın; çünkü deduplikasyon sahte “ödendi” olaylarını korumaz.

How do I handle webhook timeouts without creating duplicates?

Olay güvenli şekilde saklandıktan sonra alımı hızlıca onaylayın ve ağır işleri arka plana atın. Yavaş çalışan handlerlar daha fazla zaman aşımına yol açar, bu da yeniden denemeleri artırır ve eğer herhangi bir şey tamamen idempotent değilse çift güncelleme riskini yükseltir.

What should I do when events arrive out of order?

Sadece durumu ilerleten değişiklikleri uygulayın ve eski olayları yoksayın. Mümkünse olay zaman damgalarını kullanın ve basit bir durum önceliği uygulayın (örneğin, refunded, paid'ın üzerine yazmamalı; canceled, active'in üzerine yazmamalıdır).

How can I avoid granting access twice when a renewal webhook is retried?

Her olay için yeni bir yetkilendirme satırı oluşturmayın. “Kullanıcı/ürün/dönem başına bir yetki olduğundan emin ol” gibi bir upsert kuralı uygulayın, sonra tarihler/limitleri güncelleyin ve hangi olay kimliğinin değişikliğe neden olduğunu denetim için kaydedin.

Why should invoice and entitlement updates be in one transaction?

Fatura, abonelik ve yetkilendirme değişikliklerini tek bir veritabanı işlemi (transaction) içinde yazın, böylece hepsi birlikte başarılı olur ya da birlikte geri alınır. Bu, “fatura ödendi ama erişim verilmedi” veya “erişim iptal edildi ama iade kaydı yok” gibi bölünmüş durumları engeller.

Can I implement this safely in AppMaster without writing custom backend code?

Evet. Uygun bir eşleşen WebhookEvents modeli oluşturun ve benzersiz event ID alanı ekleyin; ardından “zaten görüldü mü?” kontrolü yapan bir Business Process kurun ve erkenden çıkış yapın. Faturalar/abonelikler/yetkilendirmeleri Data Designer içinde açıkça modelleyin ki yeniden denemeler ve yeniden oynatmalar çoğaltma yaratmasın.

Başlaması kolay
Harika bir şey yaratın

Ücretsiz planla AppMaster ile denemeler yapın.
Hazır olduğunuzda uygun aboneliği seçebilirsiniz.

Başlayın
Güvenli fatura güncellemeleri için idempotent ödeme webhook'ları kontrol listesi | AppMaster