Ödeme sistemlerinde webhook yeniden deneme stratejisi
Qvard bir ödeme webhook'unu nasıl yeniden dener, neyin başarısız teslimat sayıldığı ve bir siparişi iki kez yerine getirmeden yeniden denemelere, tekrarlara ve kesintilere dayanan bir işleyicinin nasıl kurulacağı.
Bir ödeme webhook'u kaybolmaması ve iki kez işlenmemesi gereken bir mesajdır. Ağlar çöker, sunucular yeniden başlar; bu yüzden gönderen yeniden dener ve işleyicinizin tekrarlar düşünülerek yazılması gerekir. Bu rehber Qvard'ın nasıl yeniden denediğini, neyi hata saydığını ve bu davranışın etrafında bir işleyici ile kurtarma rutininin nasıl kurulacağını anlatıyor.
Webhook ne zaman gönderilir
Qvard webhook'u bir ödeme tamamlandığında gönderir. Bu, projenizde kayıtlı callback URL'ye giden bir POST'tur; küçük bir JSON gövdesinde id (ödemeyi oluştururken verdiğiniz tanımlayıcı) ve status bulunur, istek X-Qvard-Signature başlığında imzalanmıştır.
Eksik, reddedilmiş veya hâlâ bekleyen bir ödeme tamamlanma webhook'u üretmez. Bu ödemeleri bilmeniz gerekiyorsa panelden bakın; gönderilmeyen bir mesajı beklemeyin.
Neyin teslim edilmiş sayıldığı
Qvard bir teslimatı yalnızca uç noktanız tam olarak HTTP 200 yanıtladığında başarılı sayar. Geri kalan her şey hatadır:
201,202,204ve tüm4xxve5xxdahil başka herhangi bir durum kodu;- sunucunuz yavaş veya ulaşılamaz olduğu için zaman aşımı;
- yönlendirme: Qvard
301veya302'yi takip etmez; bu yüzdenhttp'yihttps'ye yönlendiren veya sona eğik çizgi ekleyen bir kural teslimatı başarısız kılar.
Bu kesinlik bilinçlidir. 204 No Content gayet iyi bir yanıt gibi görünür ve yine de başarısız bir teslimattır. İsterseniz boş gövdeyle 200 döndürün.
Yeniden denemeler nasıl çalışır
Başarısız bir teslimattan sonra Qvard yeniden dener. Toplamda yaklaşık altı dakikada beş deneme vardır. Buradan iki sonuç çıkar:
- Kısa bir kesinti kapsanır. Sunucunuz yeniden başlarsa veya bir dağıtım bir iki dakika sürerse sonraki bir deneme başarılı olur ve hiçbir şey kaybetmezsiniz.
- Daha uzun bir kesinti kapsanmaz. Son denemeden sonra Qvard durur. Sunucunuz bu altı dakikadan uzun süre kapalı kaldıysa bildirim kendiliğinden gelmez; o ödeme için panelden yeniden gönderin.
Yeniden denemeler nedeniyle işleyiciniz bazen aynı olayı birden fazla kez görecektir; örneğin sunucunuz işi yaptı ama yanıt dönüş yolunda kayboldu. Aşağıdaki örnek bunun için kuruldu: güncelleme yalnızca henüz ödenmemiş bir siparişi değiştirir, yerine getirme yalnızca bir satır değiştiğinde kuyruğa alınır ve yanıt her durumda 200'dür.
import os
from fastapi import FastAPI, Request, Response
from qvard import Qvard
app = FastAPI()
SECRET = os.environ["QVARD_SECRET_KEY"]
qvard = Qvard(SECRET)
@app.post("/webhooks/qvard")
async def qvard_webhook(request: Request):
try:
body = qvard.webhooks.construct_event(await request.body(), request.headers.get("X-Qvard-Signature", ""), SECRET)
except ValueError:
return Response(status_code=400)
order_id, status = body.get("id"), body.get("status")
# Idempotent: the UPDATE changes a row only for an order that is not paid yet.
if status == "completed":
changed = await db.execute(
"UPDATE orders SET state = 'paid' WHERE id = :id AND state <> 'paid'", {"id": order_id}
)
if changed:
await queue.enqueue("fulfil", order_id) # slow work after the answer
return Response(status_code=200) # exactly 200, also for repeats and unknown ordersİşleyicinizin yapması gerekenler
Dört kural neredeyse tüm sorunları kapsar:
- İmzayı doğrulayın.
X-Qvard-Signaturebaşlığını (ham gövde üzerinden, gizli anahtarınızla HMAC-SHA256) sabit zamanlı karşılaştırın ve aksi halde400yanıtlayın. Bunu işleme almadan önce yapın. Bkz. kripto ödeme webhook'ları nasıl güvenli hale getirilir. - İdempotent olun. Durum değişikliğini koşullu yapın, «henüz ödenmemişse ödendi işaretle», ideal olarak tek bir veritabanı ifadesiyle; böylece iki paralel teslimat birlikte kazanamaz.
- Hızlı yanıtlayın. Kontrol et, güncelle, kuyruğa at, tam olarak 200 yanıtla. E-postaları, dosya üretimini ve diğer sistemlere çağrıları yanıttan sonra bir kuyruktan yapın; böylece yavaş bir hizmet webhook'ta zaman aşımına dönüşmez.
- Hiç işlemeyeceğiniz şeye 200 yanıtlayın. Bilinmeyen bir sipariş veya tekrar da 200 döndürmelidir; aksi halde Qvard, zaten ele aldığınız veya hiç ele almayacağınız bir mesajı yeniden denemeye devam eder.
Qvard hatası gibi görünen kesintiler
«Webhook gelmedi» şikâyetlerinin çoğunun nedeni alıcı taraftadır:
- Bilinmeyen adreslerden gelen istekleri engelleyen bir güvenlik duvarı veya WAF, ya da bir «yakında» veya bakım sayfası.
http'denhttps'ye,www'dan çıplak alan adına veya sona eğik çizgiye bir yönlendirme.- Yanıt zaten kararlaştırıldıktan sonra bir çerçeve hatası; örneğin 200'ünüzü 500'e çeviren bir middleware istisnası.
- Yanıtlamadan önce işi yapan ve zaman aşımına takılan yavaş bir işleyici.
- Rotanın önünde bir önbellek veya CDN.
- Projede kayıtlı yanlış URL veya rotada bir yazım hatası.
Uç noktayı ağınızın dışından geçerli bir X-Qvard-Signature taşıyan bir istekle test edin ve sunucunuzun erişim günlüğünde yalnızca isteğin gelip gelmediğine değil, yanıt koduna bakın.
Kaçan bildirimler için bir kurtarma rutini
Yeniden denemeler kısa kesintileri kapsar; geri kalanı için bir güvenlik ağı ekleyin.
- Her teslimatı günlüğe yazın:
id,status, kararınız (uygulandı, tekrar, bilinmeyen sipariş, anahtar reddedildi) ve zaman. Günlükte eksik bir satır, bir boşluğu fark etme yolunuzdur. - Zamanlanmış mutabakat yapın. Günde bir kez, hâlâ ödenmemiş saydığınız siparişleri Qvard panelindeki ödemeler ve bakiyeyle karşılaştırın. Panelde tamamlanmış, sizde ödenmemiş olan her şey kaçırılmış bir bildirimdir.
- Panelden yeniden gönderin ve bu ödemeleri idempotent işleyicinizin uygulamasına izin verin.
- Uyarı kurun: bir dizi istek hata aldığında, bozuk bir uç noktayı günün sonunda değil dakikalar içinde öğrenin.
Ödeme oluşturma dahil entegrasyonun geri kalanı bir web sitesinde kripto ödemesi nasıl kabul edilir ve geliştiriciler için kripto ödeme API'si yazılarında.
FAQ
Qvard bir webhook'u kaç kez yeniden dener?
Toplamda yaklaşık altı dakikada beş deneme vardır. Sonrasında Qvard durur ve ödemenin bildirimini panelden yeniden gönderebilirsiniz.
Uç noktam hangi durum kodunu döndürmeli?
Tam olarak 200. 204 dahil başka herhangi bir durum, zaman aşımı veya yönlendirme başarısız teslimat sayılır ve yeniden denenir.
Aynı webhook iki kez gelebilir mi?
Evet; örneğin sunucunuz ilk teslimatı işledi ama yanıt kayboldu. İşleyiciyi idempotent yapın ve tekrarlara yine de 200 yanıtlayın.
Eksik veya reddedilmiş bir ödeme için webhook alır mıyım?
Hayır. Webhook bir ödeme tamamlandığında gönderilir. Diğer ödemeleri panelden kontrol edin.
