Güvenlik & Fraud

Webhook

Ödeme ve iade olaylarını gerçek zamanlı olarak sunucunuza iletiriz. Her istek HMAC-SHA256 ile imzalanır; işlemeden önce imzayı doğrulayın.

Webhook Oluştur

POST/api/WebhookX-Api-Key

Alan	Tip		Açıklama
url	string	zorunlu	Olayların gönderileceği HTTPS adres
events	string[]	zorunlu	Abone olunacak olaylar
description	string	opt	Açıklama
retryCount	int	opt	Yeniden deneme sayısı (vars. 3)
timeoutSeconds	int	opt	Zaman aşımı (vars. 30 sn)

Oluşturma yanıtında secret bir kez döner. Bu değeri güvenle saklayın — imza doğrulaması için gereklidir ve tekrar gösterilmez. Gerekirse /api/Webhook/{id}/regenerate-secret ile yenileyin.

Olay Tipleri

payment.succeeded payment.failed payment.cancelled refund.initiated refund.completed refund.failed recurring.created recurring.paused recurring.resumed recurring.cancelled

İmza Doğrulama

Her webhook isteği X-Webhook-Signature başlığı taşır. Bu değer, ham istek gövdesinin webhook secret ile HMAC-SHA256 (hex) imzasıdır. Zamanlama ataklarına karşı sabit-zamanlı karşılaştırma kullanın.

X-Webhook-Signature

HMAC-SHA256(ham gövde, secret) — hex

İmzayı doğrularken framework'ünüzün yeniden serileştirdiği gövdeyi değil, HAM (raw) istek gövdesini kullanın. Yeniden serileştirme boşluk/sıra farkı yaratıp imzayı bozar.

Test ve Loglar

Test olayı gönder	POST /api/Webhook/{id}/test
Teslimat logları	GET /api/Webhook/{id}/logs
Başarısızı yeniden gönder	POST /api/Webhook/logs/{logId}/retry
Desteklenen olaylar	GET /api/Webhook/events

Önceki← Tekrarlı Ödemeler SonrakiFraud Yönetimi →

İmza doğrulama (HMAC-SHA256)

# Gelen istekteki başlık:
#   X-Webhook-Signature: 6f2a...e91b   (hex)
# İmza = HMAC_SHA256(ham_gövde_json, webhook_secret)
# Aşağıdaki dillerde doğrulama örneklerine bakın.

using System.Security.Cryptography;
using System.Text;

bool Verify(string payload, string signature, string secret) {
    using var h = new HMACSHA256(Encoding.UTF8.GetBytes(secret));
    var hash = h.ComputeHash(Encoding.UTF8.GetBytes(payload));
    var computed = Convert.ToHexString(hash).ToLowerInvariant();
    return CryptographicOperations.FixedTimeEquals(
        Encoding.UTF8.GetBytes(computed),
        Encoding.UTF8.GetBytes(signature));
}

<?php
function verify(string $payload, string $signature, string $secret): bool {
    $computed = hash_hmac('sha256', $payload, $secret);
    return hash_equals($computed, $signature);
}

$payload   = file_get_contents('php://input');
$signature = $_SERVER['HTTP_X_WEBHOOK_SIGNATURE'] ?? '';
if (verify($payload, $signature, $webhookSecret)) {
    // olayı işle
}

const crypto = require('crypto');

function verify(payload, signature, secret) {
  const computed = crypto
    .createHmac('sha256', secret)
    .update(payload)        // ham (raw) gövde
    .digest('hex');
  return crypto.timingSafeEqual(
    Buffer.from(computed), Buffer.from(signature));
}

// Express: express.raw({ type: 'application/json' }) kullanın
app.post('/webhook', (req, res) => {
  const ok = verify(req.body.toString(),
    req.header('X-Webhook-Signature'), WEBHOOK_SECRET);
  res.sendStatus(ok ? 200 : 400);
});

{
  "event": "payment.succeeded",
  "paymentId": "9c8f2e1a-...",
  "paymentReferenceNumber": "PAY-20260819-0001",
  "amount": 149.90,
  "currency": "TRY",
  "status": "Başarılı",
  "timestamp": "2026-08-19T10:36:00Z"
}