Webhook İdempotensi ve Güvenli Yeniden Denemeler

Web3 Ödemelerinde İdempotens Neden Önemlidir

Blokzincir onay süreleri değişkenlik gösterdiğinden ve internet yönlendirmesinde geçici dalgalanmalar yaşanabileceğinden, XPayr otomatik dağıtıcısı onaylanmayan webhook'ları 5 defaya kadar yeniden dener. İdempotent bir dinleyici, mağazanızın aynı siparişi asla iki kez teslim etmemesini garanti eder.

Temel Başlık (Header) Spesifikasyonları

• X-XPayr-Delivery: Her webhook olayına atanan benzersiz UUID (örn. deliv_9f8a2c1e4d). Aynı işlem olayına ait tüm yeniden deneme girişimlerinde her zaman birebir aynıdır.
• X-XPayr-Signature: Tekrar saldırısı ve veri kurcalamasını önleyen HMAC SHA-256 özeti.
• X-XPayr-Event: Olay tanımlayıcısı (payment.confirmed, payment.failed).

Canlı Ortama Hazır Dinleyici Şablonu (PHP)

<?php
// Secure Webhook Listener with Idempotency Protection
$rawPayload = file_get_contents('php://input');
$deliveryId = $_SERVER['HTTP_X_XPAYR_DELIVERY'] ?? '';
$signature = $_SERVER['HTTP_X_XPAYR_SIGNATURE'] ?? '';

// 1. Verify HMAC Signature
$expectedSignature = 'sha256=' . hash_hmac('sha256', $rawPayload, $webhookSecret);
if (!hash_equals($expectedSignature, $signature)) {
    http_response_code(401);
    exit('Invalid signature');
}

$event = json_decode($rawPayload, true);
$orderId = $event['data']['order_id'] ?? null;

// 2. Check if this delivery or order was already processed (Atomic DB Lock)
$stmt = $pdo->prepare("INSERT INTO processed_webhooks (delivery_id, order_id, created_at) VALUES (?, ?, NOW())");
try {
    $stmt->execute([$deliveryId, $orderId]);
} catch (PDOException $e) {
    // Duplicate event detected (Unique constraint violation)
    // Return HTTP 200 OK immediately so XPayr stops retrying!
    http_response_code(200);
    echo json_encode(['status' => 'already_processed']);
    exit;
}

// 3. Fulfill Order (Guaranteed to execute exactly ONCE)
fulfillCustomerOrder($orderId, $event['data']);

http_response_code(200);
echo json_encode(['status' => 'success']);