Kripto ödeme webhook'ları: HMAC-SHA256 imza doğrulama ve tekrar denemeleri yönetme

Webhook, bir faturanın durumu değiştiğinde CryBit'in sunucunuza gönderdiği bir istektir. Bir siparişin ödendiğini öğrenmenin en güvenilir yoludur. Aynı zamanda herkese açık bir URL'dir, yani herkes buraya istek gönderebilir. Harekete geçmeden önce her isteği doğrulayın.

Ne alırsınız

İstek, JSON gövdeli bir POST'tur. Olay adı X-CryBit-Event başlığında gelir, örneğin payment.paid. İstediğiniz olayları satıcı ayarlarından seçersiniz: paid, expired, refunded, cancelled. Webhook URL'si fatura isteğinde değil, satıcı üzerinde tanımlanır.

İmzayı kontrol edin

Her webhook, t=<unix zaman>,v1=<hex> biçiminde bir X-CryBit-Signature başlığı taşır. Doğrulamak için t'yi alın, bir nokta ve ham istek gövdesiyle birleştirin, imzalama gizli anahtarınızla HMAC-SHA256 hesaplayın ve sonucu v1 ile karşılaştırın. Sabit zamanlı bir karşılaştırma kullanın. t, beş dakikadan eskiyse isteği reddedin. Her satıcının imzalama gizli anahtarı, satıcı ayarlarında entegrasyon sekmesindedir. Bu anahtar olmadan hiç kimse paid durumunu taklit edemez.

İmzayı, alındığı haliyle ham gövde üzerinden hesaplayın. JSON'u önce ayrıştırıp yeniden seri hale getirirseniz baytlar değişir ve kontrol başarısız olur.

Hızlı yanıt verin, güvenle tekrar deneyin

• Olayı kaydeder kaydetmez 2xx durum koduyla yanıt verin, ağır işi sonrasında yapın. CryBit yaklaşık on iki saniye bekler.
• Yanıt vermezseniz CryBit, artan aralıklarla tekrar dener: 15 saniye, 1 dakika, 5, 15 ve 30 dakika, ardından 2, 6 ve 24 saat. 429 dışında bir 4xx durum koduyla verilen yanıt tekrar denemeleri durdurur.
• İşlemi idempotent yapın: aynı olay birden fazla kez gelebilir. Anahtar olarak order_id'nizi ya da fatura uuid'sini kullanın ve ikinci teslimi yok sayın.
• Bir siparişi yalnızca tarayıcıdaki widget olayına dayanarak kapatmayın. Widget olayı yalnızca kullanıcı arayüzü içindir.

Herhangi bir nedenle webhook'ları kaçırırsanız fatura durumunu GET /api/v1/payments/{uuid} ile sorgulayın. Durum her zaman güvenilir kaynaktır.