Idempotency — Chống xử lý trùng lặp

Chống xử lý trùng webhook HiTechCloud Pay: do cơ chế gửi lại và phát lại, dùng trường id làm khoá duy nhất để mỗi giao dịch chỉ được xử lý đúng một lần.

Xem Markdown

Idempotency nghĩa là: dù webhook của cùng một giao dịch đến bao nhiêu lần, kết quả trong hệ thống của bạn vẫn chỉ xảy ra một lần. Đây là yêu cầu bắt buộc với mọi nghiệp vụ liên quan tới tiền.

Vì sao một giao dịch bị gửi nhiều lần?

  • Retry tự động: endpoint timeout hoặc trả mã lỗi, HiTechCloud Pay gửi lại theo lịch.
  • Replay thủ công: quản trị viên bấm 'Gửi lại' trên bảng điều khiển.
  • Mạng chập chờn: endpoint đã xử lý xong nhưng phản hồi 200 không về kịp, hệ thống coi là thất bại và gửi lại.
Trường id là duy nhất và cố định qua mọi lần gửi của cùng một giao dịch. Tuyệt đối không dùng referenceCode hay content làm khóa chống trùng vì chúng có thể trùng nhau giữa các giao dịch khác nhau.

Mẫu triển khai an toàn

BướcHành động
1Nhận webhook, đọc id.
2Chèn id vào bảng có ràng buộc UNIQUE (dùng INSERT IGNORE hoặc ON CONFLICT DO NOTHING).
3Nếu chèn thất bại vì trùng -> giao dịch đã xử lý, trả {success:true} ngay để dừng retry.
4Nếu chèn thành công -> đây là lần đầu, thực hiện nghiệp vụ (cộng tiền, kích hoạt dịch vụ).
5Luôn bọc bước 2-4 trong một transaction CSDL để tránh race condition.
Khóa UNIQUE trên id giao dịch (MySQL / MariaDB)
ALTER TABLE hitechcloud_webhook_transactions
  ADD UNIQUE KEY uniq_htc_trans_id (htc_transaction_id);
INSERT IGNORE chống trùng lặp (PHP + MySQL)
<?php
$payload = json_decode(file_get_contents('php://input'), true);

$stmt = $pdo->prepare(
  "INSERT IGNORE INTO hitechcloud_webhook_transactions
   (htc_transaction_id, gateway, transfer_amount, code, content, raw_payload)
   VALUES (?, ?, ?, ?, ?, ?)"
);
$stmt->execute([
  $payload['id'],
  $payload['gateway'],
  $payload['transferAmount'],
  $payload['code'] ?? null,
  $payload['content'],
  json_encode($payload),
]);

if ($stmt->rowCount() === 0) {
    // Da ton tai -> dung retry ngay
    echo json_encode(['success' => true, 'message' => 'Already processed']);
    exit;
}

// Lan dau tien -> cong tien / kich hoat dich vu
echo json_encode(['success' => true]);
Tương đương trên PostgreSQL
INSERT INTO hitechcloud_webhook_transactions
  (htc_transaction_id, gateway, transfer_amount, code, content, raw_payload)
VALUES ($1, $2, $3, $4, $5, $6)
ON CONFLICT (htc_transaction_id) DO NOTHING;
Mẹo: luôn trả về HTTP 200 kèm {success:true} cả khi phát hiện trùng. Nếu bạn trả lỗi, HiTechCloud Pay sẽ tiếp tục retry vô ích cho một giao dịch đã xử lý xong.