Webhook İmza Doğrulayıcı

İşletme panelinden yapılandırdığınız webhook teslimlerinin X-Kaptan-Signature-256 başlığını doğrular: signingPayload = timestamp + "." + rawBody, imza HMAC-SHA256(secret, signingPayload). timestamp, X-Kaptan-Timestamp başlığındaki epoch milisaniye değeridir.

Buradaki secret, işletme panelindeki Entegrasyon → Webhook ekranından alınan webhook imza sırrıdır — Partner API isteklerini imzaladığınız API secret'ı DEĞİLDİR.

Gövdeyi ham hâliyle yapıştırın — JSON'u parse edip yeniden serileştirmek imzayı bozar.

Secret tarayıcıdan çıkmaz

Hesaplama tamamen tarayıcıda (WebCrypto) yapılır.

Secret ve timestamp girildiğinde beklenen imza hesaplanır.

Teslim Başlıkları

BaşlıkDeğer
X-Kaptan-Signature-256t=<timestamp>,v1=<hex> — doğrulamanız gereken imza.
X-Kaptan-Signaturesha256=<hex> — aynı imzanın eski biçimi (geriye uyumluluk için).
X-Kaptan-Timestampİmzaya giren zaman damgası, epoch milisaniye.
X-Kaptan-EventOlay adı (ör. PAYMENT_SUCCEEDED).
X-Kaptan-Webhook-IdTeslim kaydının kimliği; tekrar denemelerde aynı kalır, mükerrer işlemeyi önlemek için kullanın.
X-Kaptan-ResourcePosTransaction:<transactionRef> biçiminde kaynak.
X-Kaptan-Secret-Versionİmzada kullanılan sır sürümü — sır yenilemesinde hangi sırla doğrulayacağınızı gösterir.
X-Correlation-IdDestek talepleri için korelasyon kimliği.
User-AgentKaptan-Webhook/1.0

Gövde, anahtarları alfabetik sıralı kompakt JSON'dur; imza bu ham metin üzerinden hesaplanır. 2xx dışındaki yanıtlar teslimi başarısız sayar ve olay tekrar denenir.

Olaylar ve Gövde

OlayNe zaman
PAYMENT_SUCCEEDEDTahsilat gerçekleşti (provizyonda kapatma anında).
PAYMENT_AUTHORIZEDProvizyon açıldı, tutar bloke — tahsilat değildir.
PAYMENT_FAILEDÖdeme başarısız.
PAYMENT_REFUNDEDİade yapıldı.
PAYMENT_VOIDEDİşlem iptal edildi.
PAYMENT_REVERSEDİşlem otomatik geri alındı.
PAYMENT_SETTLEDHakediş tamamlandı.
CHARGEBACK_RECEIVED / CHARGEBACK_WON / CHARGEBACK_LOSTTers ibraz süreci.
MERCHANT_APPROVED / MERCHANT_REJECTEDİşletme başvurusu sonucu.
TESTPanelden gönderilen deneme olayı.
AlanAnlamı
eventTypeOlay adı.
transactionRefİşlem referansı — Partner API uçlarındaki değerle aynı.
orderNumberÖdemede gönderdiğiniz sipariş numarası.
amount / currencyİşlem tutarı ve para birimi.
paymentMethod / installment / threedÖdeme yöntemi, taksit sayısı ve 3D Secure bilgisi.
status / successİşlem durumu; success tahsilat gerçekleşmişse true.
merchantIdİşletme kimliği.

Tahsilat kaydı üzerinden yayınlanan olaylarda gövde status, success, merchantId, installment, threed yerine checkoutId, referenceCode, capturedDate, refundedDate alanlarını taşıyabilir. Aynı işlem için aynı olay yalnız bir kez kuyruğa alınır.