Idempotence des Webhooks et Relances Sécurisées

Pourquoi l'Idempotence est Essentielle dans les Paiements Web3

Les temps de confirmation blockchain étant variables et le routage internet pouvant subir des pics transitoires, le répartiteur automatique XPayr relance les webhooks non acquittés jusqu'à 5 fois. Un écouteur idempotent garantit que votre boutique ne livre jamais deux fois la même commande.

Spécifications des En-têtes Clés

• X-XPayr-Delivery: UUID unique attribué à chaque événement webhook (ex. deliv_9f8a2c1e4d). Toujours identique lors de toutes les tentatives de relance d'un même événement.
• X-XPayr-Signature: Empreinte HMAC SHA-256 empêchant toute altération ou attaque par rejeu.
• X-XPayr-Event: Identifiant de l'événement (payment.confirmed, payment.failed).

Modèle d'Écouteur Prêt pour la Production (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']);