Kripto Ödeme Webhook'ları: Olaylar, Güvenlik ve Güvenilir Sipariş Teslimi

Kripto ödeme webhook'ları, bir fatura durumu her değiştiğinde ödeme geçidinin sunucuna gönderdiği HTTP istekleridir: transfer algılandı, zincirde onaylandı, eksik ödendi, fazla ödendi veya süresi doldu. İşleyicin imzayı doğrular, siparişi günceller ve teslimatı tetikler. Kripto ödemeler asenkron geldiği için, müşteri sayfandan ayrıldıktan dakikalar sonra, doğruluğun kaynağı tarayıcı değil webhook'tur.

Bu rehber entegrasyonun webhook tarafına odaklanıyor: beklenen olaylar, nasıl doğrulanacakları, aynı olay iki kez geldiğinde işlemenin nasıl güvenli tutulacağı ve nasıl test edilip izleneceği. Fatura oluşturmak için kripto ödeme API entegrasyonu rehberimize bak.

Neden yoklama veya yönlendirme yerine webhook?

• Yönlendirme kanıt değildir — müşterinin "teşekkürler" sayfana dönmesi paranın gelip gelmediği hakkında hiçbir şey söylemez.
• Yoklama israftır — her açık fatura için birkaç saniyede bir API'ye sormak ölçeklenmez ve yine gecikir.
• Webhook itme modelidir — geçit bir şey değiştiği anda sana doğrulayabileceğin bir imzayla haber verir.

Alacağın olaylar

Bunlar mistKET'in kullandığı olay adlarıdır. Diğer geçitler farklı adlarla benzer durumlar kullanır; bunları tek bir yerde kendi sipariş durumlarınla eşle.

İmzayı doğrulamak

Herkes herkese açık bir URL'ye POST isteği gönderebilir; bu yüzden her webhook kimlik doğrulamasından geçmelidir. mistKET her gönderimi HMAC-SHA256 ile imzalar ve şu başlıkları yollar:

• X-Mistket-Event — olay adı.
• X-Mistket-Timestamp — imzaya dahil edilen Unix zamanı.
• X-Mistket-Signature — sha256= ve ardından webhook gizli anahtarınla {timestamp}.{raw body} değerinin HMAC'i.
• X-Mistket-Delivery — loglama için gönderim kimliği.

1. Ham gövdeyi oku — JSON ayrıştırmadan önce, çünkü yeniden kodlama baytları değiştirir.
2. HMAC'i yeniden hesapla — zaman damgası, nokta ve ham gövde üzerinden, webhook gizli anahtarınla.
3. Sabit zamanlı karşılaştır — hash_equals, hmac.compare_digest veya crypto.timingSafeEqual kullan.
4. Eski zaman damgalarını reddet — örneğin beş dakikadan eski olanları, tekrar oynatma saldırılarını engellemek için.
5. Ancak sonra ayrıştır ve işle — ve hızlıca 2xx yanıt dön.

Yapı standart HMAC modelini izler; gizli anahtarı sunucuda tut ve sızarsa değiştir.

Callback URL'sini seçmek ve korumak

Normal sayfalarından ayrı, /webhooks/mistket gibi özel bir HTTPS yolu kullan ve her faturayı oluştururken bunu callback URL olarak gönder. Bu yolu CSRF korumasından, önbellekten ve yönlendirmelerden muaf tut; 301 yönlendirmesi veya önbelleğe alınmış bir yanıt, webhook'ların sessizce başarısız olmasının yaygın nedenlerindendir. Oturum çerezi isteme; geçit giriş yapmış bir kullanıcı değildir, kimlik doğrulama HMAC imzasıdır. Son olarak her gönderimi olay, sipariş numarası ve yanıt koduyla logla ki "webhook geldi mi?" sorusunu saniyeler içinde yanıtlayabilesin.

Idempotency: aynı olay iki kez gelebilir

Uç noktan zaman aşımına uğrar veya hata dönerse geçit saatlerce artan aralıklarla yeniden dener. Ağ aksaklıkları da zaten işlediğin bir olayı tekrar getirebilir. Bu yüzden işleyicin idempotent olmalı:

• Sipariş numarasını anahtar al — faturanın referans verdiği siparişi bul.
• Mevcut durumu kontrol et — sipariş zaten teslim edildiyse onayla ve başka bir şey yapma.
• İşlem veya kilit kullan — iki paralel gönderimin ikisi de ürünü göndermesin.
• Gönderim kimliğini sakla — tekrarları ayıklamak için faydalıdır.

Sipariş durumlarını olaylara göre tasarlamak

Basit bir durum makinesi hataların çoğunu önler: bekliyor → onaylanıyor (paid ile) → ödendi (confirmed ile) → teslim edildi; eksik ödendi ve süresi doldu için yan dallar. Yalnızca ileri geçişlere izin ver. Örneğin invoice.confirmed'dan sonra gelen bir invoice.paid, siparişi asla geri götürmemeli. Süresi dolmuş faturalara gelen geç ödemeler siparişi sessizce yeniden açmak yerine inceleme kaydı oluşturmalı.

Zor durumları yönetmek

• Eksik ödeme — müşteriye eksik tutarı tam olarak söyle ve aynı ödeme sayfasına gönderebileceğini belirt; kısmi ödemeler toplanır.
• Fazla ödeme — teslim et, sonra politikana göre bakiye veya iade transferine karar ver.
• Süre dolumu — stoğu serbest bırak ve müşteri hâlâ almak istiyorsa yeni bir fatura sun.
• Yanlış ağ — bu kodla değil destekle çözülür; önlemek için ağı ödeme sayfasında açıkça göster.

Test ve izleme

1. Test uç noktası aç — HTTPS üzerinden, başlıkları ve ham gövdeleri loglayarak.
2. Her olayı tetikle — küçük gerçek ödemelerle paid, confirmed, underpaid, overpaid ve expired.
3. Bir gönderimi tekrar oynat — işleyicinin tekrarı yok saydığını doğrula.
4. İmzayı boz — bir baytı değiştir ve isteğin reddedildiğini kontrol et.
5. Gönderim loglarını izle — satıcı paneli her denemeyi, yanıt kodunu ve işlem hash'ini gösterir.
6. Hatalarda uyarı al — 2xx dışı yanıtlardaki artış siparişlerin teslim edilmediği anlamına gelir.

Botlar ve ücretli topluluklar da aynı modeli izler; sohbet akışına nasıl oturduğunu Telegram botunda kripto ödeme kabul etme yazımızda gör.

mistKET ile webhook'lar

mistKET her fatura durumu için HMAC imzalı webhook'lar gönderir, başarısız gönderimleri artan aralıklarla yeniden dener ve satıcı panelinde gönderim loglarını, beklenen ve alınan tutarları ve işlem hash'lerini gösterir. API istekleri de aynı şekilde imzalanır; tek bir yardımcı fonksiyon iki yönü de karşılar.

İstek ve webhook örneklerini geliştirici bölümünde incele, fiyatlandırmaya bak ve anahtarlarını satıcı girişinden yönet. Erişim için Telegram'da @mistnetwork üzerinden başvur.