Olay
Ödeme, oyun oturumu, KYC kontrolü, bonus, oyuncu profili veya başka bir nesnedeki değişikliğin kaydı.
Dokümantasyon / Webhook'lar
Webhook'lar ve olay teslimatı
Sistemler arasında güvenilir durum ve olay teslimatı kurun: mesaj oluşturma ve imza doğrulamadan alındı onayına, yeniden teslimata ve hata izlemeye kadar.
Olaylar
durumlar ve değişiklikler
İmza
orijinallik doğrulaması
Tekrarlar
yeniden teslimat
İzleme
geçmiş ve teşhis
Olay akışı
Oluşturmadan alındı onayına
01
Olay oluşturun
Kimliği, türü, zamanı, nesneyi, durumu ve ilgili verileri belirtin.
02
İmzalayın ve gönderin
Olayı HTTPS üzerinden, imza ve sınırlı zaman aşımıyla gönderin.
03
Alındığını onaylayın
Doğrulamadan sonra olayı kaydedin ve hızla başarılı bir HTTP yanıtı döndürün.
04
Hata durumunda tekrar deneyin
Teslimatı artan aralıklarla tekrar deneyin ve teslim edilemeyen olayları inceleme için saklayın.
Genel bakış
Webhook bir durum değişikliğini bildirir
Gönderen teslimatı tekrar deneyebilir; bu nedenle alıcı kaynağı doğrulamalı, alındığını onaylamalı ve her olayı yalnızca bir kez uygulamalıdır.
Alındı onayı
Alıcı, olayı doğrulayıp güvenilir şekilde kaydettikten sonra başarılı bir HTTP yanıtı döndürür.
Kurtarma
Yeniden teslimat ve mutabakat, sistemlerden birinin geçici olarak kullanılamaması sonrasında verilerin yeniden eşitlenmesine yardımcı olur.
Olay yapısı
Bir olay neleri içermeli
Tutarlı mesaj yapısı; doğrulamayı, yönlendirmeyi, yinelenen işlemlere karşı korumayı ve farklı olay türlerinin desteklenmesini kolaylaştırır.
Olay kimliği
Sistemin yeniden teslimatı tanıması ve işlem geçmişini bulması için kullanılan benzersiz değer.
Olay türü
Gerçekleşen değişikliği ve nasıl işleneceğini tanımlayan açık ve sabit ad.
Oluşturulma zamanı
Olayın oluşturulduğu tarih ve saat, kararlaştırılan format ve saat diliminde.
İlgili nesne
Ödeme, oyuncu, tur, talep, bonus veya başka bir nesnenin türü ve kimliği.
Şema sürümü
Sürüm numarası, aktif entegrasyonları bozmadan mesaj yapısının güvenli biçimde değiştirilmesine yardımcı olur.
İşlem korelasyonu
Orijinal isteğin, işlemin, oturumun veya ilişkili eylemler zincirinin kimliği.
Bağlam
Doğru yönlendirme için gereken marka, proje, pazar, ortam, sağlayıcı ve diğer veriler.
Olay verileri
Değişikliği işlemek veya sonraki API isteğini yapmak için gereken minimum alan seti.
İmza ve doğrulama
Olayın gerçekliğini ve bütünlüğünü doğrulama
Verileri değiştirmeden önce alıcı güvenli bağlantıyı, imzayı, oluşturulma zamanını ve benzersiz olay kimliğini doğrular.
01
Ham mesajı alın
JSON formatını değiştirmeden önce imzayı ham istek gövdesi üzerinde doğrulayın.
02
Zaman damgasını kontrol edin
Olay zamanı izin verilen pencerenin dışındaysa isteği reddedin.
03
İmzayı doğrulayın
Kararlaştırılan secret ve HMAC veya dijital imza algoritmasını kullanın.
04
Kimliği kontrol edin
Olayın daha önce uygulanmadığını doğrulayın ve doğrulama sonucunu kaydedin.
Teslimat ve tekrarlar
HTTP yanıtları ve yeniden teslimat
Gönderen başarılı alımı, geçici hatayı ve kalıcı hatayı ayırt etmelidir; alıcı ise hızlı ve açık yanıt vermelidir.
Başarılı HTTP yanıtı
Olayın doğrulandığını ve sonraki işlem için güvenilir biçimde kaydedildiğini onaylar.
Sınırlı zaman aşımı
Gönderene yanıt vermeden önce uzun işlem yapmayın — önce olayı kaydedin.
Yeniden teslimat
Geçici ağ hatası, kullanılamama veya yanıt alınmaması durumunda teslimatı tekrar deneyin.
Artan tekrar aralığı
Ek yük oluşturmamak için denemeler arasındaki gecikmeyi kademeli artırın.
Teslim edilemeyen olay kuyruğu
Tüm denemeler tükendikten sonra olayı teşhis ve manuel işleme için saklayın.
Manuel yeniden teslimat
Operatör yeni bir işlem oluşturmadan seçilen olayı yeniden gönderebilir.
Teslimat izleme
Deneme sayısını, yanıtları, son hatayı ve sonraki teslimat zamanını takip edin.
Uyarılar
Hatalar arttığında, tekrarlar tükendiğinde veya olaylar kuyrukta biriktiğinde ekibi uyarın.
Olay işleme
Yinelenen işlemlere karşı koruma ve durum sıralaması
Alıcı tek teslimata veya olayların katı sırasına güvenmemelidir.
Yalnızca bir kez uygulayın
Verileri değiştirmeden önce olay kimliğini kaydedin.
Yinelenen olayı ek borçlandırma, alacaklandırma veya durum değişikliği olmadan onaylayın.
Olayı nesne ve mevcut durumuyla ilişkilendirin.
Olayı ve iş değişikliğini tek bir tutarlı işlem olarak kaydedin.
Sıralama ve güncellik
Zaman damgasını, sıra numarasını veya olay sürümünü karşılaştırın.
Eski bir olay geç geldiğinde nesneyi güncelliğini yitirmiş bir duruma geri döndürmeyin.
Yalnızca durumlar arasında geçerli geçişlere izin verin.
Şüphe varsa API üzerinden nesnenin güncel durumunu sorgulayın.
Test
Lansmandan önce neler test edilmeli
Başarılı teslimatı, geçersiz imzaları, yinelenen olayları, yavaş yanıtları, sıra dışı olayları ve arıza sonrası kurtarmayı test edin.
Geçersiz imza
Değiştirilmiş mesaj, bilinmeyen anahtar, süresi dolmuş zaman damgası ve desteklenmeyen algoritma.
Yeniden teslimat
Aynı olay, işleme tamamlanmadan önce ve tamamlandıktan sonra birkaç kez gelir.
Yavaş yanıt
Alıcı çok geç yanıt verir, bağlantı kesilir veya alındı onayı gönderene ulaşmaz.
Sıra dışı işleme
Nihai durum ara durumdan önce gelir ve daha eski bir olay daha yeni olaydan sonra teslim edilir.
Kullanılamayan endpoint
HTTP 5xx hatalarını, DNS, TLS, istek sıklığı limitlerini ve tüm tekrar denemelerinin tükenmesini test edin.
Teslimat geçmişi
Tüm denemeler, yanıtlar, hatalar ve manuel yeniden teslimat sonuçları olay kimliğine göre aranabilir olmalıdır.
Lansman öncesi kontrol listesi
Canlı teslimat; güvenlik, yinelenen işlemlere karşı koruma, yeniden teslimat ve hata izleme doğrulandıktan sonra etkinleştirilir.
Test ve canlı ortamlar farklı endpoint'ler ve imzalama secret'ları kullanır.
İmza, ham mesaj ve oluşturulma zamanı birlikte kullanılarak doğrulanır.
Olay kimliği saklanır ve işlemlerin birden fazla kez yürütülmesini engeller.
Alıcı, olayı kaydettikten sonra hızlı biçimde başarılı bir HTTP yanıtı döndürür.
Tekrarlar, artan aralıklar ve manuel yeniden teslimat yapılandırılmıştır.
Teslimat geçmişi ve kimliğe göre arama destek ekibinin erişimine açıktır.
Güvenilir olay teslimatı kurmanız mı gerekiyor?
Olay listesini, alıcı endpoint'leri ve durum geçişi kurallarını bize iletin. APIACE mesaj yapısını, imza doğrulamasını, yeniden teslimatı ve hata izlemeyi tanımlamaya yardımcı olacaktır.