عدم تكرار معالجة الويب هوك وإعادة المحاولة الآمنة

لماذا تُعد خاصية عدم التكرار ضرورية في مدفوعات Web3

نظراً لتفاوت أوقات تأكيد البلوكتشين واحتمال حدوث تذبذبات مؤقتة في توجيه الإنترنت، يعيد موزع XPayr الآلي إرسال أحداث الويب هوك غير المؤكدة حتى 5 مرات. يضمن المستمع غير المتكرر عدم تنفيذ متجرك لنفس الطلب مرتين أبداً.

مواصفات الترويسات الرئيسية

• X-XPayr-Delivery: معرّف UUID فريد مخصص لكل حدث ويب هوك (مثل deliv_9f8a2c1e4d). يبقى متطابقاً دائماً عبر جميع محاولات إعادة الإرسال لنفس حدث المعاملة.
• X-XPayr-Signature: تجزئة HMAC SHA-256 التي تمنع التلاعب بالبيانات أو هجمات إعادة التشغيل.
• X-XPayr-Event: معرّف نوع الحدث (payment.confirmed, payment.failed).

نمط مستمع جاهز لبيئة الإنتاج (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']);